一、前提条件
开始配置前，请确认以下条件已就绪：
·可用的 AGS API Key。
·客户端（Cursor 或 Claude Desktop）支持通过远程 HTTP MCP server 注册自定义工具。
·一个已创建的沙箱工具的名称；如不指定，默认使用 code-interpreter-v1。
·已选择公开可用地域。示例使用 ap-guangzhou，你可替换为其他已开放地域。
注意：说明：
·X-API-KEY Header
POST /code HTTP/1.1Host: mcp.ap-guangzhou.tencentags.comX-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 模式。