获取 AX Code · 免费文档
AX Code.
zh-CN
English繁體中文简体中文日本語한국어FrançaisDeutschBahasa IndonesiaItalianoPortuguês (Brasil)РусскийEspañolTürkçeTiếng Việt
开始使用

本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

MCP 集成

状态：生效 范围：当前状态 最近审阅：2026-10-09 负责人：ax-code 运行时

AX Code 可以连接到 Model Context Protocol 服务器，以获取外部工具、提示和资源。MCP 很强大，因此 AX Code 把 MCP 配置和 MCP 提供的内容当作信任边界。

实验性浏览器桥接是另一条路径。它启动一个隔离的 Chrome 窗口，并可以调用页面通过 WebMCP 注册的工具。从终端界面启用它；步骤和批准层级见 WebMCP 浏览器桥接。

信任模型

来自用户控制的配置源的 MCP 条目默认受信任：

  • 全局用户配置；
  • 受管配置；
  • 显式的 AX_CODE_CONFIG；
  • 内联的 AX_CODE_CONFIG_CONTENT；
  • 通过已授权本地运行时路由的运行时添加。

来自共享或网络发现来源的 MCP 条目默认不受信任：

  • 项目 ax-code.json；
  • 工作树 .ax-code 配置；
  • 远程的 well-known 配置。

不受信任的 MCP 条目显示为 needs_trust。在该条目被信任之前，AX Code 不会启动本地 MCP 命令、连接远程 MCP URL、暴露 MCP 工具模式、列出提示/资源，或为该条目启动 OAuth。

信任命令

列出 MCP 状态：

ax-code mcp list

信任一个服务器指纹：

ax-code mcp trust <name>

撤销对当前服务器指纹的信任：

ax-code mcp untrust <name>

从当前项目配置中移除一个已配置服务器：

ax-code mcp remove <name> --force

添加 --global 可改为从全局配置移除。移除停留在所选范围内，若该处没有该服务器则失败。省略 --force 可在确认之前审阅目标路径。

信任存储在仓库之外，作用域是当前项目加上服务器指纹。更改实质性的 MCP 配置，例如命令、URL、OAuth 模式、头或显式环境值，会使先前的信任失效。

运行时权限

信任只允许 MCP 服务器参与运行时。单个 MCP 工具调用仍然经过 AX Code 权限。

MCP 工具权限键保持现有的 <server>_<tool> 形态。当 AX Code 能从工具参数识别稳定资源时，它会用更窄的模式询问，例如：

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

未知的参数形态默认询问，而不提供宽泛的持久批准。

提示、资源与内容

MCP 提示和资源是不受信任的上下文。AX Code 通过权限门控 MCP 提示使用和 MCP 资源读取，把取回的文本标为不受信任的 MCP 内容，并在大段文本进入模型上下文之前截断它。

MCP 工具元数据和输出也是有界的：

  • 过大的模式在暴露工具之前被拒绝；
  • 长描述有上限；
  • 本地 MCP 标准错误日志被缩短，明显的秘密模式被脱敏；
  • 面向模型的 MCP 工具内容使用与用户可见工具输出相同的截断结果。

用于 HTML 和 Web 开发的 Playwright MCP

在处理 HTML 游戏、Web 应用，或根目录有 index.html 的任何项目时，AX Code 把该项目检测为 Web 项目，并阻止智能体自主打开你的浏览器。相反，智能体报告变更并等待你刷新。

对于基于截图的验证，连接 Playwright MCP 服务器：

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

或手动把它加入 ax-code.json：

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

CDP 附加模式

如果 Chrome 以 --remote-debugging-port=9222 运行，AX Code 会自动检测并在 CDP 附加模式下连接。智能体可以调用 browser_screenshot 捕获实时标签页，而不打开新窗口或夺走焦点。

要启用 CDP 启动 Chrome：

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

无头回退

没有打开的 Chrome CDP 端口时，@playwright/mcp 会启动无头 Chromium 实例。截图仍在 TUI 中内联渲染。

全局安装

如果 @playwright/mcp 已全局安装（npm install -g @playwright/mcp），AX Code 直接使用 playwright-mcp 二进制文件，而不是通过 npx 运行它，首次使用更快。

安全说明

Playwright MCP 服务器对你的浏览器获得很大能力。当它来自项目配置（ax-code.json）时，在你用 ax-code mcp trust playwright 显式授予信任之前它不受信任。全局用户配置条目在首次批准后自动连接。

服务器模式

变更类 MCP HTTP 路由除了一般服务器保护之外，还需要进程本地的运行时授权头。这保护添加、连接、断开和认证 MCP 服务器等本地运行时控制动作。只读 MCP 状态仍可通过 GET /mcp 获得。

Figma MCP

Figma 桌面

在 Figma 桌面应用中打开设计文件，切换到 Dev Mode，并在检查面板中启用桌面 MCP 服务器。仅打开应用并不会启用服务器。见 Figma 的桌面设置说明。

把此条目加入你的 AX Code 配置：

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

对于项目配置，审阅该条目并授予信任：

ax-code mcp trust figma-desktop

type: "remote" 选择 HTTP/SSE 传输，包括本机上的 HTTP 服务器。type: "local" 选择使用 stdio 的子进程。

环回 HTTP MCP 策略

allowLoopback 默认为 false。把它设为 true 时，仅在配置的方案、主机名和端口上允许 localhost、127.0.0.1 或 [::1] 的 HTTP(S)。它要求环回 URL 且不嵌入凭据。共享的项目条目仍需要信任；启用该选项会使此前没有它而授予的信任失效。

重定向、SSE 消息端点和 OAuth 请求必须留在同一来源上。其他端口、公共目的地、私有网络地址和云元数据端点仍然被阻止。localhost 的 DNS 应答必须全部是环回地址，并在每次连接时固定。依赖外部 OAuth 发行者的本地服务不受此选项支持。Figma Desktop 请使用 oauth: false。

如果连接被拒绝，检查桌面 MCP 服务器已启用并在端口 3845 上监听。仅切换到 localhost 或禁用 OAuth 并不会启用环回访问。

Figma 远程 OAuth（mcp.figma.com）

Figma 的托管端点是 https://mcp.figma.com/mcp。Figma 要求其 MCP Catalog 中有已批准的客户端。客户端开发者必须遵循 Figma 的远程访问登记要求。

被拒绝的动态登记并不能仅靠创建普通的 Figma OAuth 应用或提供其客户端 ID 和秘密来解决。可用时请使用为已批准 MCP 集成签发的凭据。当官方端点拒绝登记时，AX Code 会报告 Catalog 要求。环回访问并不授予托管服务器批准。

基于令牌的模板

内置的 figma 模板运行分开的 figma-developer-mcp 包，并带 FIGMA_API_KEY。它与 Figma 官方的桌面和托管 MCP 服务器不同。