Get AX Code · FreeDocs (EN)
AX Code.
en
English
Get started

English documentation · runtime 7.24.4 · SDK 2.6.7. Content is maintained with runtime development; see each guide's scope and review date.

MCP Integrations

Status: Active Scope: current-state Last reviewed: 2026-10-09 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.

The experimental browser bridge is a separate path. It launches an isolated Chrome window and can call tools a page registers through WebMCP. Enable it from the terminal UI; the steps and approval tiers are in WebMCP browser bridge.

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>

Remove a configured server from the current project’s config:

ax-code mcp remove <name> --force

Add --global to remove from global config instead. Removal stays within the selected scope and fails if the server is absent there. Omit --force to review the target path before confirming.

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

Figma Desktop

In the Figma desktop app, open a design file, switch to Dev Mode, and enable the desktop MCP server in the inspect panel. Opening the app alone does not enable the server. See Figma’s desktop setup instructions.

Add this entry to your AX Code configuration:

{
  "mcp": {
    "figma-desktop": {
      "type": "remote",
      "url": "http://127.0.0.1:3845/mcp",
      "allowLoopback": true,
      "oauth": false
    }
  }
}

For a project configuration, review the entry and grant trust:

ax-code mcp trust figma-desktop

type: "remote" selects HTTP/SSE transport, including HTTP servers on this machine. type: "local" selects a subprocess using stdio.

Loopback HTTP MCP policy

allowLoopback defaults to false. Setting it to true permits HTTP(S) on localhost, 127.0.0.1, or [::1] at the configured scheme, hostname, and port only. It requires a loopback URL without embedded credentials. Shared project entries still require trust; enabling the option invalidates trust previously granted without it.

Redirects, SSE message endpoints, and OAuth requests must stay on that same origin. Other ports, public destinations, private network addresses, and cloud metadata endpoints remain blocked. DNS answers for localhost must all be loopback addresses and are pinned for each connection. Local services that depend on an external OAuth issuer are not supported by this option. Use oauth: false for Figma Desktop.

If the connection is refused, check that the desktop MCP server is enabled and listening on port 3845. Switching to localhost or disabling OAuth alone does not enable loopback access.

Figma Remote OAuth (mcp.figma.com)

Figma’s hosted endpoint is https://mcp.figma.com/mcp. Figma requires an approved client in its MCP Catalog. Client developers must follow Figma’s remote access registration requirements.

A rejected dynamic registration is not resolved merely by creating an ordinary Figma OAuth application or supplying its client ID and secret. Use credentials issued for an approved MCP integration when available. AX Code reports the Catalog requirement when registration is rejected by the official endpoint. Loopback access does not grant hosted-server approval.

Token-based template

The built-in figma template runs the separate figma-developer-mcp package with FIGMA_API_KEY. It is distinct from Figma’s official Desktop and hosted MCP servers.