Skip to main content
Model Context Protocol (MCP) extends Ona Agent with external tools like GitHub, Linear, and browser automation. MCP servers run as separate processes in your environment and communicate over stdio or HTTP.

​
Configuration

Create .ona/mcp-config.json in your repository: 
{
  "mcpServers": {
    "github": {
      "name": "github",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "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}"
      },
      "timeout": 30,
      "toolDenyList": ["search_code"]
    },
    "playwright": {
      "name": "playwright",
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"],
      "timeout": 60
    }
  },
  "globalTimeout": 30
}

​
Transport types

Each server uses either stdio or HTTP transport. Ona detects the transport from your config:
  • Set command for stdio transport (runs a local process)
  • Set url for HTTP transport (connects to a remote endpoint)
A server cannot have both command and url.

​
Configuration options

FieldTransportDescription
namebothDisplay name for the server (defaults to the map key)
commandstdioExecutable to run the server
argsstdioCommand arguments
urlHTTPServer endpoint (must start with http:// or https://)
headersHTTPHTTP headers sent with requests (supports ${exec:...} and ${file:...})
envstdioEnvironment variables (supports ${exec:...} and ${file:...})
timeoutbothPer-server timeout in seconds (default: 30)
toolDenyListbothTools to block (supports wildcards like delete_*)
workingDirstdioWorking directory for the server process
disabledbothSet true to disable without removing config
Set globalTimeout at the top level of the config to apply a default timeout to all servers.

​
Checking MCP server status

Click the MCP Integrations button in the conversation input to see server status. Each server shows whether it is connected, disabled, or experiencing errors.
MCP Integrations panel showing available servers with status indicators and error messages

​
Examples

​
Stdio transport (local process)

@executeautomation/playwright-mcp-server runs as a local process via npx: 
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"],
      "timeout": 60
    }
  }
}

​
HTTP transport (remote server)

Connect to an MCP server running over HTTP. Use url instead of command: 
{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${exec:printenv MCP_API_TOKEN}"
      },
      "timeout": 60
    }
  }
}
headers supports ${exec:...} and ${file:...} expansion, like env. Inject tokens at runtime instead of committing secrets.

​
Credentials

Use Ona Secrets to inject credentials into env (stdio) or headers (HTTP): 
{
  "env": {
    "API_TOKEN": "${exec:printenv API_TOKEN}",
    "SERVICE_KEY": "${exec:your-secrets-cli get service/key}"
  }
}
For HTTP servers, inject tokens via headers: 
{
  "headers": {
    "Authorization": "Bearer ${file:/run/secrets/api-token}"
  }
}
  • Environment variables: ${exec:printenv VAR_NAME}
  • Files: ${file:/path/to/secret}
  • External stores: ${exec:aws secretsmanager get-secret-value ...}
Avoid committing secrets to source control. Provision them at runtime using Ona Secrets.

​
DevContainer requirements

MCP servers run inside your environment. The base image must include the tools they need (npx for Node-based servers, docker for container-based servers). If a server fails to start, verify the required runtime is in your Dev Container image.

​
Applying configuration changes

After creating or modifying .ona/mcp-config.json:
  1. Commit the file to your repository
  2. Create a new environment, or rebuild the Dev Container in an existing one with gitpod environment devcontainer rebuild

​
Troubleshooting

​
MCP tools not appearing

The agent may not list MCP tools when asked, but can still invoke them. Type /support-bundle in your Ona conversation to verify servers are connecting.

​
Configuration errors cause rebuild loop

If your MCP configuration has errors, the Dev Container rebuild can loop. Stop the environment manually, fix the configuration, then rebuild.

​
Organization controls

MCP controls toggle in organization settings showing the option to enable or disable MCP servers
Organization owners can disable MCP in Settings > Agents. When disabled:
  • .ona/mcp-config.json files are ignored
  • Agent operates with built-in tools only
  • External MCP connections are blocked
See Audit logs to review changes.