Ona Agent supports the Model Context Protocol (MCP) to access external tools and resources through MCP servers. Use MCP to extend Ona Agent beyond built-in capabilities with integrations such as GitHub, Linear, or browser automation.

​
What is MCP?

Model Context Protocol (MCP) is a standardized protocol that enables AI agents to communicate with external services via client/server architecture:
  1. MCP servers provide tools and resources (for example, GitHub MCP server, Linear (MCP directory), Playwright MCP server)
  2. Ona Agent acts as the MCP client and manages connections
  3. The AI accesses tools via MCP using JSON-RPC 2.0 over stdio or HTTP
Ona Agent → MCP Client → External MCP Server → External Service

​
Prerequisites

None! MCP is available out of the box on all tiers.

​
Configure MCP for a project

Create a .ona/mcp-config.json file in your repository to configure MCP servers.

​
Minimal example

{
  "mcpServers": {
    "github": {
      "name": "github",
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server"],
      "disabled": false,
      "timeout": 30
    }
  }
}

​
Advanced configuration

{
  "mcpServers": {
    "github": {
      "name": "github",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "disabled": false,
      "timeout": 30,
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${exec:printf 'protocol=https\nhost=github.com\n' | git credential fill 2>/dev/null | awk -F= '/password/ {print $2}' 2>/dev/null}"
      },
      "toolDenyList": ["search_code"],
      "workingDir": "/workspace"
    },
    "linear": {
      "name": "linear",
      "command": "/usr/local/bin/linear-mcp-go",
      "args": ["serve", "--write-access=false"],
      "disabled": false,
      "env": { "LINEAR_API_KEY": "${exec:printenv LINEAR_API_KEY}" }
    }
  },
  "globalTimeout": 30,
  "logLevel": "info"
}

​
Common server configurations

​
GitHub

Server link: GitHub MCP server (GitHub Docs) Tip: Ensure a Git credential helper is configured so git credential fill returns a Personal Access Token (for example, run gh auth login). 
{
  "mcpServers": {
    "github": {
      "name": "github",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "disabled": false,
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${exec:printf 'protocol=https\nhost=github.com\n' | git credential fill 2>/dev/null | awk -F= '/password/ {print $2}' 2>/dev/null}"
      },
      "toolDenyList": ["search_code"]
    }
  }
}

​
Linear

Server link: Search for Linear MCP servers 
{
  "mcpServers": {
    "linear": {
      "name": "linear",
      "command": "/usr/local/bin/linear-mcp-go",
      "args": ["serve", "--write-access=false"],
      "disabled": false,
      "env": { "LINEAR_API_KEY": "${exec:printenv LINEAR_API_KEY}" }
    }
  }
}

​
Playwright (browser automation)

Server link: @executeautomation/playwright-mcp-server (npm) 
{
  "mcpServers": {
    "playwright": {
      "name": "playwright",
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"],
      "disabled": false,
      "timeout": 60
    }
  }
}

​
Security and controls

​
Process isolation

  • Each MCP server runs as a separate process within your environment. You set per-server environment variables in the MCP config (env), and if you run the server via Docker you can additionally leverage container isolation
  • Timeouts can be set per server (timeout) and globally (globalTimeout) in your MCP config
  • Defaults: If not set, per-server timeout defaults to 30s and initial connection timeout defaults to 60s
  • Gitpod environments run in isolated virtual machines for strong workload isolation. See Linux runners overview
Timeouts example: 
{
  "globalTimeout": 45,
  "mcpServers": {
    "github": {
      "timeout": 30,
      "name": "github",
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]
    }
  }
}

​
Credential management

We recommend using Gitpod Secrets to inject MCP credentials into Ona environments:
  • Use Environment Variable secrets for tokens (consume with \${exec:printenv YOUR_VAR} in MCP config)
  • Use File secrets when tools expect files (consume with \${file:/your/mount/path})
Learn more: Secrets overview, Environment variables, Files
Use your organization’s secret management approach to inject credentials at runtime. Common options:
  • Mounted files provided by your environment or CI/CD (reference with ${file:/path/to/secret})
  • Environment variables injected at startup (for non-sensitive config or when files are not feasible)
  • On-demand retrieval with ${exec:...} to fetch from an external secret store (for example, AWS Secrets Manager, GCP Secret Manager, Vault)
Examples: 
{
  "env": {
    "GITHUB_TOKEN": "${exec:printenv GITHUB_TOKEN}",
    "LINEAR_API_KEY": "${exec:your-secrets-cli get linear/api-key}"
  }
}
Guidance:
  • Prefer ${exec:...} (fetch at runtime) or mounted files over plain environment variables for sensitive data
  • Avoid committing secrets to source control; provision them at runtime via your platform of choice

​
Tool filtering

{
  "toolDenyList": ["dangerous*", "rm*", "delete_*"]
}
For blocking system commands executed by Ona Agent itself, see Command deny list.

​
Organization controls (Enterprise)

MCP controls in settings for an organization

Organization owners can control MCP usage across their organization in settings. To disable MCP:
  1. Navigate to Settings > Agents
  2. Locate the MCP controls
  3. Toggle MCP off to disable Model Context Protocol across all environments in your organization
When MCP is disabled at the organization level:
  • .ona/mcp-config.json files in projects are ignored
  • Ona Agent operates with built-in tools only
  • External MCP server connections are blocked
  • Changes apply to new Ona Agent sessions; existing sessions should be restarted to apply the policy
This enterprise control helps compliance teams enforce security policies while developers can still keep MCP configurations in code for future use. See Audit logs to review organization-level changes.