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 session 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

Ona reads MCP configuration once at the start of each agent execution. Changes are not picked up mid-conversation, regardless of whether they are in .ona/mcp-config.json, organization integrations, or the org-level MCP toggle.

​
Local config (.ona/mcp-config.json)

After creating or modifying the file:
  1. Save the file in your workspace
  2. Start a new agent execution: open a new Ona conversation, or wait for the current execution to finish and send a new message
The agent reads the file from your workspace filesystem at the start of each execution. You do not need to rebuild the Dev Container or create a new environment. Commit the file to your repository when you’re ready to share the config with new environments.

​
Organization integrations (dashboard)

Changes to MCP integrations in Settings > Integrations take effect on the next agent execution. No environment changes are needed.

​
Organization MCP toggle

Enabling or disabling MCP in Settings > Agents takes effect on the next agent execution.

​
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 session to verify servers are connecting.

​
Configuration errors

If your MCP configuration has syntax errors or invalid server definitions, the agent logs the error and skips the misconfigured server. Check the MCP Integrations panel in the conversation input for error details.

​
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.