MCP tool servers

Wrappers pass an mcp map to the backend so it can use MCP tool servers. The shape differs slightly per backend; the concept is the same.

Supported transportsCopy Anchor Link

A local stdio serverCopy Anchor Link

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORKSPACE_DIR}"]
    }
  }
}

A remote HTTP serverCopy Anchor Link

{
  "mcp": {
    "my-tools": { "type": "http", "url": "http://localhost:8002/mcp" }
  }
}

In a2a-opencode use "type": "remote" instead of "http".

Authenticated serversCopy Anchor Link

Hosted servers such as Linear or Notion need credentials. Add a headers map. Values support ${ENV_VAR} substitution, so secrets never live in the config file.

{
  "mcp": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "headers": { "Authorization": "Bearer ${LINEAR_API_KEY}" }
    }
  }
}

LINEAR_API_KEY=lin_xxx a2a-claude --config ./config.json

For stdio servers, args and env values support the same substitution, so the spawned server receives its tokens without them being committed.

OAuth (OpenCode)Copy Anchor Link

When a remote server requires an OAuth2 flow:

{
  "mcp": {
    "my-oauth-tools": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write" }
    }
  }
}

Prefer headers with an environment variable whenever you control the token.

Scope tools tightlyCopy Anchor Link

An MCP server runs as a separate process with its own permissions. Give it the narrowest arguments and environment it needs, and use the backend's own allow and deny controls where available (for example enabledTools and disabledTools in a2a-codex). See the security guide.