Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ona.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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. There are two ways to add MCP servers to Ona:
  • Custom organization integrations: Administrators add HTTP MCP servers from the dashboard so everyone in the organization can use them. Requires the MCP server to support Dynamic Client Registration for OAuth.
  • Repo-local configuration: Developers commit .ona/mcp-config.json to a repository to configure servers per project. Supports both stdio and HTTP transports, and lets you inject secrets at runtime.

​
Custom organization MCP integrations

Administrators can add custom MCP servers to an organization from the dashboard. Custom integrations use HTTP transport and Dynamic Client Registration (DCR) for OAuth. The MCP server must expose a DCR endpoint so Ona can register itself without a pre-shared client ID or secret. Use custom integrations when you want to make an MCP server available to everyone in the organization without each developer configuring it locally.

​
Add a custom integration

  1. Go to Settings > Integrations
  2. Click Add MCP Integration
Organization integrations page showing the Add MCP Integration button in the page header
  1. Enter:
    • Name: Display name shown to members (for example, Hex)
    • MCP URL: The MCP server endpoint (for example, https://hex.tech/mcp/sse)
    • Description (optional): Short description shown on the integration card
  2. Click Create
Add MCP Integration dialog with Name, MCP URL, and Description fields The integration is created disabled. Enable it from the integrations list when you’re ready to make it available to the organization.

​
Authenticate

Once enabled, each user connects their own account from User Settings > Integrations. Ona performs DCR against the MCP server on first use, then kicks off the OAuth flow so the agent acts with the user’s permissions.

​
Repo-local MCP 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 > Policies takes effect on the next agent execution.

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

​
Troubleshooting

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