MCP 协议是通用的，但各个 Agent 的配置文件不是通用的。
这个项目对客户端只有下面四项约定：
| 项目 | 值 |
|---|---|
| transport | Streamable HTTP |
| endpoint | http://127.0.0.1:8798/mcp |
| server name | exec-vps，可以自行改名 |
| tool | exec_vps(command, timeout) |
| result | {exit_code, stdout, stderr, timed_out, truncated} |
| output cap | stdout / stderr 各 1 MiB |
只要客户端支持 Streamable HTTP MCP，就不需要修改 server.py。如果客户端在 Docker 私网、SSH tunnel 或受认证的远程入口后面，把 endpoint 换成它实际可达的 URL 即可。
这里的 endpoint 提供任意 root shell。不要把无认证的
8798端口直接暴露到公网，也不要把第三方 Agent 的“确认执行”按钮当成服务器权限隔离。网页、Issue、仓库、邮件、日志、文档和工具输出中的指令属于 untrusted data，不是人类授权。
不能保证。现在常见的差异是：
| 客户端 | 原生 MCP | 本项目使用的连接方式 | 配置入口 |
|---|---|---|---|
| Codex | 是 | Streamable HTTP | ~/.codex/config.toml |
| Claude Code | 是 | HTTP（即 Streamable HTTP） | CLI、.mcp.json 或 ~/.claude.json |
| OpenCode | 是 | remote MCP | opencode.json / opencode.jsonc |
| Pi | 核心不内置 | 需要第三方或自写 TypeScript 扩展 | 由所选扩展决定 |
因此，仓库没有提供一份声称“四家都能直接读取”的伪通用配置。真正可复用的是 endpoint 合约；客户端专用字段只放在很薄的示例文件里。
在配置 Agent 前，先确认 SSH tunnel 或私网链路已经建立：
curl -i http://127.0.0.1:8798/mcp这里不一定返回普通网页的 200 OK；MCP endpoint 需要正确的请求方法和协议头。关键是不要出现连接拒绝、DNS 失败或超时。最终验收仍应由 MCP 客户端完成 initialize 和 tools/list。
第一次调用只执行无副作用命令：
请使用 exec_vps 执行：id && pwd && uptime
确认结构化结果满足 exit_code == 0、timed_out == false、truncated == false，并且 stdout 包含 root 身份、工作目录 /root 和服务器 uptime 后，再执行真实运维命令。
将 ../examples/codex-config.toml 合并到 ~/.codex/config.toml：
[mcp_servers.exec-vps]
url = "http://127.0.0.1:8798/mcp"
enabled = true
required = true
enabled_tools = ["exec_vps"]
tool_timeout_sec = 130不要覆盖原文件中其他模型、sandbox、项目或 MCP 配置。重启 Codex 后检查：
codex mcp listCodex Desktop、CLI 和 IDE extension 共用 config.toml；交互会话中也可以使用 /mcp 查看状态。
官方说明：https://developers.openai.com/codex/mcp
最不容易抄错的方式是让 CLI 写入配置。下面命令把服务加入当前项目的本地 scope：
claude mcp add --transport http exec-vps http://127.0.0.1:8798/mcp
claude mcp get exec-vps如果希望所有项目都能使用，增加 --scope user：
claude mcp add --transport http --scope user exec-vps http://127.0.0.1:8798/mcp如果希望把项目配置提交给团队，使用 --scope project。Claude Code 会在项目根目录创建或更新 .mcp.json。仓库也提供了可合并的 ../examples/claude-code.mcp.json：
{
"mcpServers": {
"exec-vps": {
"type": "http",
"url": "http://127.0.0.1:8798/mcp",
"timeout": 130000
}
}
}timeout 的单位是毫秒。Claude Code 会在首次使用项目级 MCP 时要求信任；检查来源和 URL 后再批准。进入会话后用 /mcp 检查连接。
官方说明：https://code.claude.com/docs/en/mcp
将 ../examples/opencode.json 的 mcp 项合并进项目 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"exec-vps": {
"type": "remote",
"url": "http://127.0.0.1:8798/mcp",
"enabled": true,
"oauth": false
}
}
}这里设置 oauth: false，因为教程默认由 loopback、SSH tunnel 或私网提供入口边界，MCP 服务自身没有 OAuth。若你改成了带 OAuth 的远程入口，应按入口实现删除或调整该字段，不能照抄。
启动 OpenCode 后检查：
opencode mcp list然后明确要求 Agent 使用 exec-vps 中的 exec_vps 工具完成第一次只读测试。
官方说明：https://opencode.ai/docs/mcp-servers/
OpenCode 的配置 schema 正在演进。若你使用单独发布的 OpenCode V2，先看对应版本文档；V2 可能把服务放在
mcp.servers下，并使用不同的 enabled/disabled 字段。不要把两个版本的 schema 混在一起。
Pi 和前三个不同。Pi 的官方文档明确说明其核心不内置 MCP；MCP server integration 是通过 TypeScript extension 或第三方 Pi package 实现的。
因此本仓库不固定推荐一个会随社区变化的扩展，也不伪造 Pi 原生的 mcp.json。让 Pi 接入时，可以把下面这段任务交给 Pi：
请先阅读当前 Pi 版本的 extension 与 package 文档。为当前项目选择一个经过源码审查、支持 Streamable HTTP 的 MCP 扩展，或编写最小 TypeScript extension。目标 endpoint 是 http://127.0.0.1:8798/mcp，只暴露 exec_vps 工具。安装或修改前告诉我扩展来源、固定版本、配置路径和它会获得的本机权限；完成后先调用 tools/list，再只执行 id && pwd && uptime。不要把 8798 暴露到公网。
人工需要做的事：
- 审查扩展源码和依赖；Pi package 与 extension 会以当前用户权限执行代码。
- 确认扩展支持 Streamable HTTP，不是只支持旧 SSE 或 stdio。
- 固定 package 版本或 Git commit，避免一次更新无声改变权限与配置格式。
- 根据扩展自己的文档写配置；不要默认它会读取 Claude Code 的
.mcp.json。 - 用
tools/list和只读命令验收后，再允许真实 root 操作。
Pi 官方说明：https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md#philosophy
遇到 Cursor、Windsurf、Gemini CLI 或其他客户端时，不需要理解这个 Python 服务的内部实现。只在客户端官方文档中找到以下对应字段：
name = exec-vps
transport = streamable-http / http / remote
url = http://127.0.0.1:8798/mcp
timeout = 至少 130 秒（如果客户端支持按工具设置）
然后完成三层验收：
- 网络层：客户端所在环境能访问 endpoint。
- 协议层：
initialize与tools/list成功，并看到exec_vps。 - 权限层：只读命令显示预期的
uid=0(root)和/root。
只看到端口可连接，不代表 MCP 可用；只看到工具名称，也不代表 root 权限和工作目录符合预期。