MCP 服务器

Ante 支持连接至 Model Context Protocol (MCP) 服务端，将其提供的工具动态挂载到智能体中。服务可作为本地子进程通过 stdio 通信，也可通过 Streamable HTTP 连接，其工具调用体验与内置工具完全一致。

配置

MCP 服务器在 ~/.ante/settings.json 的 mcp_servers 映射表中声明。Key 为本地服务标识；Value 描述如何启动或连接该服务。

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "remote": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

字段	必填	说明
`command`	stdio 必填	启动服务进程的可执行程序；与 `url` 互斥
`url`	Streamable HTTP 必填	服务的 Streamable HTTP 端点；与 `command` 互斥
`transport`	否	`stdio`、`streamable-http` 或 `http`（`streamable-http` 的别名）。省略时根据 `command` 或 `url` 推断
`args`	否	传递给命令的参数列表（仅 stdio）
`env`	否	注入给服务进程的环境变量（仅 stdio）
`headers`	否	每个请求都会携带的 HTTP 请求头（仅 Streamable HTTP）。值支持 `${NAME}`、`${NAME:-default}` 和 `${session_id}`。参见认证
`enabled_tools`	否	显式白名单工具列表。若为空或省略，则默认暴露该服务的所有工具

使用 stdio 时，Ante 启动命令子进程，通过其 stdin/stdout 进行 MCP 协议通信，并将 stderr 转发至日志。

使用 Streamable HTTP 时（需 Ante v0.2.12 或更新版本），Ante 直接连接 url。请将上方示例 URL 替换为服务的 Streamable HTTP 端点。无需 mcp-remote 等桥接程序，远程连接也不依赖 Node.js。迁移已有桥接配置时，将 command 和 args 替换为 url，并移除 env 条目；若使用工具白名单，可保留 enabled_tools。

command 与 url 必须且只能设置一个。显式指定的 transport 必须与之匹配。旧版 HTTP+SSE（transport: "sse"）不受支持。配置冲突、不支持的传输方式，或 URL 服务中非空的 args、env，会使该服务在预热时失败并显示具体原因。

请直接填写端点 URL：Ante 不会跟随 HTTP 重定向。

认证

远程服务有两种认证方式。

OAuth 登录。 大多数托管服务（Linear、Notion 等）支持 OAuth。只需配置 url，然后登录一次：

ante auth login linear

Ante 会自动发现该服务的登录方式，打开浏览器，并以服务名称存储登录结果，之后自动刷新。运行 ante auth logout linear 可清除登录。若未存储任何凭据，Ante 会以无凭据方式连接，需要登录的服务会提示这一点。

在 headers 中提供 Token。 对于使用 API 密钥或个人访问令牌的服务，设置 Authorization 请求头即可。Ante 会原样发送，并跳过 OAuth 登录。建议从环境变量读取 Token，避免写入设置文件：

{
  "mcp_servers": {
    "linear": { "url": "https://mcp.linear.app/mcp" },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

其他请求头同样会被发送，${session_id} 会替换为当前会话的 ID。若某个 ${NAME} 既无值也无默认值，该服务会在连接时失败，并指出缺失的变量。

工具命名规范

由服务端提供的每个工具在智能体中会统一命名为 mcp__<server>__<tool>。非字母数字字符会自动替换为下划线 _。例如名为 my-server 的服务中名为 do.thing 的工具将暴露为 mcp__my_server__do_thing。

MCP 工具同样遵循 --tools / --include-tools / --exclude-tools 命令行过滤。若基础 --tools 未声明 MCP 工具则会被剔除。若想独立控制每个服务暴露哪些工具而不受会话过滤影响，请使用 enabled_tools：

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled_tools": ["read_text_file", "write_file"]
    }
  }
}

生命周期与异步预热

在交互式 TUI 中，MCP 服务的初始化在后台**异步惰性（lazily）**进行，确保守护进程保持即时响应。当会话启动时：

SessionStart 与初始的 ExtensionRefreshed 会立即触发 —— 输入框可即时使用。
后台任务并发连接所有配置的 MCP 服务端。每次握手尝试有 15 秒截止时间，之后另有 15 秒用于获取全部工具列表分页。
所有服务的发现流程完成后，成功发现的工具会一起注册，并在下一轮 Turn 中可用（当前正在运行的轮次保持工具 Schema 冻结快照）。
预热完成后触发第二次 ExtensionRefreshed，使得 /mcp 面板填充展示每个服务发现的工具列表。

进度通过分组信息通知展示给用户（InfoBlockStart 加上后续的 InfoBlockAppend 事件 —— 参见协议参考手册）：

* Warming up 4 MCP servers — tools become available as servers connect.
  └ MCP ready: 4/4 servers connected, 60 tools registered.

连接失败（或获取工具列表失败）的服务端会被记录到日志并跳过，作为预热通知块下的子行提示。本地服务进程在整个会话期间保持存活，并在守护进程退出时终止。

无头单次运行（ante -p）会在首个提示词前阻塞等待直至 MCP 预热完成。轮次的工具 Schema 在轮次开始时冻结，以此确保配置的 MCP 工具在单轮无头任务中立即可用。ante doctor 完全跳过 MCP 预热。

协议兼容性

两种传输方式下，Ante 都先尝试 initialize。若服务端以 JSON-RPC 错误拒绝，Ante 会建立新连接（stdio 会重新启动子进程），并尝试 2026-07-28 版本的 server/discover，另给 15 秒截止时间。超时、断连和其他握手失败会直接报告，不走此回退。stdio 服务的协议消息应输出到 stdout，诊断信息应输出到 stderr。

Ante 会响应服务端 ping，但不会声明 sampling、elicitation 或 roots 能力。采样请求返回 method-not-found，信息征询被拒绝，根目录列表为空。

工具调用超时

每个 MCP 工具调用设有 10 分钟截止时间，防止外部服务卡死导致轮次无限挂起。设置环境变量 ANTE_MCP_TOOL_TIMEOUT 为正整数秒数可修改该超时：

ANTE_MCP_TOOL_TIMEOUT=120 ante

零、负数或无法解析的值保持 600 秒默认值。该配置仅针对 tools/call；不改变上述的初始化或工具列表获取超时。

调用超时或被中断时，Ante 会尽力针对该请求发送 notifications/cancelled，同时保留共享服务连接。取消通知并不保证服务端已停止执行任务。

工具结果

纯文本结果在 ToolEnd.result_json 中仍为可读字符串。富内容结果保留完整的 MCP 结果对象，包括内容块、structuredContent 与错误状态。Ante 还会将支持的文本、图片及内嵌 PDF 传给模型；结构化数据会补充到模型输入中，但不会重复等价的 JSON 文本块。资源链接只提供描述，不会自动抓取；音频及不支持的二进制内容保留在客户端结果中，并向模型提供文本提示。图片在进入模型历史前会验证并缩放；无效图片会被替换为省略提示，原始数据仍保留在客户端结果中。

`/mcp` 命令面板

在 TUI 中输入 /mcp 可查看已配置的所有 MCP 服务。选择器列出每个服务的连接状态、暴露工具数量与启动命令或远程 URL。在服务上按 Enter 可查看工具详情（说明与参数），按 d 可从 settings.json 中移除该服务。

新增服务需直接编辑 ~/.ante/settings.json；当前选择器暂不包含在 TUI 内新增的流程。

权限审批

MCP 工具默认不需要审批确认。若需管控特定工具，请使用 --exclude-tools 或权限规则。

配置​

认证​

工具命名规范​

生命周期与异步预热​

协议兼容性​

工具调用超时​

工具结果​

/mcp 命令面板​

权限审批​

配置

认证