帮你快速理解、总结文档立即下载
文档中心>Agent Runtime>操作指南>快速开始>用 MCP 连接 Claude/Cursor

用 MCP 连接 Claude/Cursor

最近更新时间：2026-09-15 14:51:25
本文档已由 AI 辅助审校
我的收藏

本页目录：

AGS 提供托管的远程 HTTP MCP 服务，对于支持远程 HTTP MCP 且兼容 AGS 鉴权方式的客户端，您可以将 Agent Sandbox Code MCP 添加到 Cursor 或 Claude Desktop，让模型调用代码执行、命令执行和文件读写能力。使用该托管服务无需获取源码或自行部署 MCP Server，但需要提前准备 AGS API Key、沙箱工具、可用地域，并完成客户端配置。

前提条件

开始配置前，请确认以下条件已就绪：
可用的 AGS API Key。
客户端（Cursor 或 Claude Desktop）支持通过远程 HTTP MCP server 注册自定义工具。
一个已创建的沙箱工具的名称；如不指定，默认使用 code-interpreter-v1。
已选择公开可用地域。示例使用 ap-guangzhou，您可替换为其他已开放地域。
说明：
mcp.{region}.tencentags.com 是 AGS 对外公开的 MCP 接入域名格式，不是用户自建或源码部署地址。
建议优先通过 X-API-KEY Header 传递 API Key。只有客户端不支持 Header 时，再使用 URL 查询参数 api_key 作为兼容方式。
X-API-KEY Header

POST /code HTTP/1.1
Host: mcp.ap-guangzhou.tencentags.com
X-API-KEY: <your-ags-api-key>
兼容方式
https://mcp.ap-guangzhou.tencentags.com/code?api_key=<your-ags-api-key>

步骤 1：确认接入参数和模式

远程 HTTP MCP 服务接入需要以下参数：
配置项
是否必填
说明
url
是
MCP 服务地址，推荐格式为 https://mcp.{region}.tencentags.com/code。
X-API-KEY
推荐
通过 Header 传递 API Key。
api_key
按需
Header 不可用时的兼容写法。
toolname
否
沙箱工具的名称，默认值为 code-interpreter-v1。
mode
否
沙箱管理模式，支持 auto 和 manual，默认值为 auto。
两种模式的差异如下：
模式
适用场景
生命周期行为
可用 Tool
auto
适合交互式对话，例如用户连续要求模型创建一个 Python 文件、执行该文件、修改文件、再次运行、查看运行结果
首次调用时自动创建沙箱实例，同一会话复用，会话结束后自动清理。
run_code、run_command、write_file、read_file、get_sandbox、set_sandbox_timeout
manual
适合需要明确管理沙箱实例的场景，显式控制 沙箱实例的创建、复用和删除。
不自动创建沙箱实例，由您显式创建、使用和删除沙箱实例。
run_code、run_command、write_file、read_file、set_sandbox_timeout、create_sandbox 和 delete_sandbox；除 create_sandbox 之外，所有针对具体 Sandbox 的操作都需要传入 sandbox_id。
auto 模式的可用 Tool
run_code：在当前沙箱实例中运行代码
run_command：在当前沙箱实例中执行命令
write_file：向当前沙箱实例写入文件
read_file：从当前沙箱实例读取文件
get_sandbox：获取当前会话关联的沙箱实例信息
set_sandbox_timeout：调整当前沙箱实例的超时时间
manual 模式的可用 Tool
create_sandbox：创建沙箱实例并返回 sandbox_id
delete_sandbox：删除指定的沙箱实例
如果是首次接入，建议从 auto 模式开始；当任务需要显式复用同一沙箱实例的状态时，再切换到 manual 模式。

步骤 2：配置 Cursor

Cursor 通过 mcp.json 注册远程 HTTP MCP 服务。常见配置文件位置如下：
项目级：.cursor/mcp.json
用户级：~/.cursor/mcp.json
在配置文件中添加以下内容（以 auto 模式为例）：
{
  "mcpServers": {
    "ags-code-mcp": {
      "url": "https://mcp.ap-guangzhou.tencentags.com/code?toolname=code-interpreter-v1&mode=auto",
      "headers": {
        "X-API-KEY": "${AGS_API_KEY}"
      }
    }
  }
}
字段说明：
url：MCP 服务地址，包含 toolname 和 mode 参数。
headers.X-API-KEY：您的 AGS API Key。
如果需要切换地域，把 ap-guangzhou 替换为对应地域标识；如果需要显式控制生命周期，把 mode=auto 改为 mode=manual。如果客户端不支持自定义 Header，可将 API Key 追加为 URL 查询参数 api_key=<your-api-key>。

步骤 3：配置 Claude Desktop

Claude Desktop 同样可以接入该远程 HTTP MCP 服务。在 MCP 配置界面中填写以下信息：
MCP 服务地址：https://mcp.ap-guangzhou.tencentags.com/code?toolname=code-interpreter-v1&mode=auto
鉴权 Header：X-API-KEY: <your-api-key>
如果需要切换地域，把 ap-guangzhou 替换为对应地域标识；如果需要显式控制生命周期，把 mode=auto 改为 mode=manual。保存配置后，重新加载 MCP 设置，使客户端重新发现可用 Tool。
说明：
Claude Desktop 的界面字段名称可能随版本变化，但核心接入信息保持不变：同一个 MCP 服务地址、同一组鉴权 Header，以及相同的 toolname / mode 参数。

步骤 4：验证连接

完成配置后，先确认客户端已发现正确的 Tool 集合：
auto 模式应发现 6 个 Tool：run_code、run_command、write_file、read_file、get_sandbox、set_sandbox_timeout
manual 模式应发现 7 个 Tool：run_code、run_command、write_file、read_file、set_sandbox_timeout、create_sandbox 和 delete_sandbox
建议按以下顺序验证功能：
1. 运行一段最小 Python 代码：运行 Python 代码 print("hello from ags")，并返回 stdout。
预期结果：客户端返回 "hello from ags"。
2. 执行一个简单命令：在沙箱实例中执行命令 pwd，并返回 stdout。
预期结果：客户端返回当前工作目录路径。
3. 验证文件写入和读取：把 Hello, MCP 写入 /tmp/demo.txt，然后读回文件内容。
预期结果：客户端返回 Hello, MCP。
如果使用 manual 模式，请先调用 create_sandbox 获取 sandbox_id，再把同一个 sandbox_id 传给 run_code、run_command、write_file、read_file 和 set_sandbox_timeout。
注意：
如果客户端返回 SESSION_NOT_FOUND，说明当前会话已过期，或服务端已重建。请重新初始化 MCP 连接，然后再继续验证。

步骤 5：清理测试资源

验证完成后，建议及时清理测试资源：
auto 模式：结束当前测试会话，服务会按会话自动回收沙箱实例。
manual 模式：调用 delete_sandbox 删除当前 sandbox_id 对应的沙箱实例。
如果您为本次联调单独创建了测试 API Key，请按现有凭证管理流程停用或删除它。

结果验证

出现以下现象时，说明接入已成功：
Cursor 或 Claude Desktop 的 Tool 列表中，出现了与当前 mode 对应数量的 AGS Code MCP Tool。
run_code、run_command 和文件读写请求返回了实际执行结果，而不是"无法访问工具"之类的纯文本说明。
manual 模式下，客户端能先拿到 sandbox_id，再用同一个 sandbox_id 完成后续调用，且 delete_sandbox 能正常返回删除成功。

后续操作

需要延长会话空闲时间时，使用 set_sandbox_timeout 调整超时策略。
需要把沙箱实例的生命周期交给业务流程统一编排时，改用 manual 模式。

中国站