MCP Integrations

July 19, 2026 · View on GitHub

Status: Active Scope: current-state Last reviewed: 2026-05-26 Owner: ax-code runtime

AX Code can connect to Model Context Protocol servers for external tools, prompts, and resources. MCP is powerful, so AX Code treats MCP configuration and MCP-provided content as a trust boundary.

Trust Model

MCP entries from user-controlled config sources are trusted by default:

  • global user config;
  • managed config;
  • explicit AX_CODE_CONFIG;
  • inline AX_CODE_CONFIG_CONTENT;
  • runtime additions through authorized local runtime routes.

MCP entries from shared or network-discovered sources are not trusted by default:

  • project ax-code.json;
  • worktree .ax-code config;
  • remote well-known config.

Untrusted MCP entries show as needs_trust. AX Code does not spawn local MCP commands, connect remote MCP URLs, expose MCP tool schemas, list prompts/resources, or start OAuth for that entry until it is trusted.

Trust Commands

List MCP status:

ax-code mcp list

Trust one server fingerprint:

ax-code mcp trust <name>

Revoke trust for the current server fingerprint:

ax-code mcp untrust <name>

Trust is stored outside the repository and is scoped to the current project plus the server fingerprint. Changing material MCP config, such as command, URL, OAuth mode, headers, or explicit environment values, invalidates previous trust.

Runtime Permissions

Trust only allows the MCP server to participate in the runtime. Individual MCP tool calls still go through AX Code permissions.

MCP tool permission keys keep the existing <server>_<tool> shape. When AX Code can identify a stable resource from tool arguments, it asks with a narrower pattern, such as:

  • url:https://api.example.com/resource
  • uri:mcp-resource
  • path:src/index.ts
  • repo:owner/name
  • db:database.table

Unknown argument shapes ask without offering broad durable approval by default.

Prompts, Resources, And Content

MCP prompts and resources are untrusted context. AX Code gates MCP prompt use and MCP resource reads through permissions, labels fetched text as untrusted MCP content, and truncates large text before it enters the model context.

MCP tool metadata and outputs are also bounded:

  • oversized schemas are rejected before tool exposure;
  • long descriptions are capped;
  • local MCP stderr logs are shortened and obvious secret patterns are redacted;
  • model-facing MCP tool content uses the same truncation result as the user-visible tool output.

Playwright MCP for HTML and Web Development

When working on HTML games, web apps, or any project with an index.html at root, AX Code detects the project as a web project and prevents the agent from autonomously opening your browser. Instead, the agent reports changes and waits for you to refresh.

For screenshot-based verification, connect the Playwright MCP server:

ax-code mcp --discover   # auto-suggests playwright in web projects

Or add it manually to ax-code.json:

{
  "mcp": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--cdp-url", "http://localhost:9222"]
    }
  }
}

CDP Attach Mode

If Chrome is running with --remote-debugging-port=9222, AX Code auto-detects it and connects in CDP attach mode. The agent can call browser_screenshot to capture the live tab without opening a new window or stealing focus.

To launch Chrome with CDP enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Headless Fallback

Without an open Chrome CDP port, @playwright/mcp launches a headless Chromium instance. Screenshots still render inline in the TUI.

Global Install

If @playwright/mcp is installed globally (npm install -g @playwright/mcp), AX Code uses the playwright-mcp binary directly instead of running it via npx, which is faster on first use.

Security Note

The Playwright MCP server gains significant capability over your browser. When sourced from project config (ax-code.json), it is untrusted until you explicitly grant trust with ax-code mcp trust playwright. Global user config entries auto-connect after first approval.

Server Mode

Mutating MCP HTTP routes require a process-local runtime authorization header in addition to general server protections. This protects local runtime-control actions such as adding, connecting, disconnecting, and authenticating MCP servers. Read-only MCP status remains available through GET /mcp.

Figma MCP

AX Code bundles a local Figma template backed by the figma-developer-mcp npm package. Use it with a personal access token:

ax-code mcp add   # From template → figma
# Provide your FIGMA_API_KEY when prompted

Figma Remote OAuth (mcp.figma.com)

Figma's remote MCP endpoint (https://mcp.figma.com/mcp) advertises a registration_endpoint but returns HTTP 403 Forbidden to clients that are not on Figma's allowlist during dynamic client registration (RFC 7591). This means the "Custom remote → No pre-registered client ID" path cannot succeed for Figma out of the box.

To use the remote endpoint, register an OAuth application with Figma and provide the issued credentials in your config:

{
  "mcp": {
    "figma-remote": {
      "type": "remote",
      "url": "https://mcp.figma.com/mcp",
      "oauth": {
        "clientId": "YOUR_FIGMA_CLIENT_ID",
        "clientSecret": "YOUR_FIGMA_CLIENT_SECRET"
      }
    }
  }
}

For most local development workflows, the token-based local template (figma-developer-mcp) is simpler and does not require OAuth registration.