@proxycept/mcp — 到 Proxycept MCP 服务器的 stdio 桥接

一个轻量级 stdio↔HTTP 桥接。它在 stdio 上运行一个模型上下文协议服务器，并将每条 JSON-RPC 消息原封不动地转发到 Proxycept MCP 端点（默认为 https://proxycept.com/api/mcp），同时携带您的 API 令牌作为 Bearer 标头。

大多数人不需要这个包。 Proxycept MCP 服务器是一个托管的 HTTP 服务器——Claude Desktop 和 Cursor 可以通过 URL 和 Authorization 标头直接连接，无需安装。这个包的存在是为了那些只支持 stdio 的 MCP 客户端，以及因为 npx 是目录列表期望的安装习惯。

对于无需安装的路径、工具目录和安全模型，请参阅 proxycept.com/docs → “Connect Claude or Cursor”，或 docs/user-manual.md §14。设置 → API 令牌中也有相同的配置可供复制，指向该部署并命名您选择的令牌——令牌值仅在创建时显示一次，因此该块带有一个您需要替换的占位符。

它不是什么

它不包含任何工具列表、工具模式或 Proxycept 特定的逻辑。tools/list 由服务器响应，而不是由这个包响应。这是有意为之：服务器是工具目录的唯一真实来源，因此服务器端添加或更改的工具无需在此发布，也不存在版本漂移需要支持。如果您正在阅读本文是因为您想为某个工具名称添加特殊情况，那说明设计出了问题。

要求

• Node.js 20 或更新版本（node --version）。

• 一个 Proxycept API 令牌（prx_live_…）——在 proxycept.com/settings 的设置 → API 令牌中获取。

使用只读令牌

将令牌创建为只读。这是默认设置，也是安全边界，而不是建议。

Proxycept 的读取工具返回捕获的 HTTP 流量——您账户未创作的内容。来自某个上游的恶意响应体可能被模型读取，就像它是一条指令（“提示注入”）。简单来说：

一个 read_write MCP 令牌意味着您的代理捕获的任何内容都可以写入您的 Proxycept 配置。

来自他人服务器的响应体，如果被写成指令的样子，就会成为您账户中的模拟路由、拦截模式或停止的配置文件。只读令牌使得该链在 Proxycept 内部无法完成：注入的指令没有任何可调用的内容。

将 Proxycept 工具返回的任何内容视为不可信数据，而不是指令——特别是如果您还连接了其他可以获取 URL、运行 shell 或写入文件的 MCP 服务器。

如果您确实需要读写权限

仅用于您有意让其更改设置的客户端。那么，请满足以下所有条件：

1. 创建一个单独的令牌（不要升级您用来读取流量的那个）。

2. 切勿在您的客户端中为 Proxycept 工具调用启用“始终允许”。

3. 不要在读取捕获流量的同一会话中使用它——这正是使注入指令可操作的组合。

读写令牌仍然无法做到的一件事：重放捕获的请求。 replay_flow 会使用捕获的凭据向第三方重新发送真实请求，因此需要人类在 Proxycept Web 控制台中批准（设置 → 连接您的 AI 客户端）。您的 AI 客户端无论持有何种令牌，都无法批准自己的重放。

配置——将令牌放在环境中，而不是配置文件中

您的 MCP 客户端配置是磁盘上的纯文本 JSON，通常位于同步到云存储的目录中。粘贴在那里的 prx_live_… 令牌是一个长期有效的凭据，存在于您未曾考虑过的备份中。优先使用环境变量。

Claude Desktop（claude_desktop_config.json）、Cursor（~/.cursor/mcp.json）和大多数其他客户端使用相同的格式：

{
  "mcpServers": {
    "proxycept": {
      "command": "npx",
      "args": ["-y", "@proxycept/mcp"],
      "env": {
        // Read from your shell environment; the secret itself stays out of this file.
        "PROXYCEPT_API_TOKEN": "${PROXYCEPT_API_TOKEN}"
      }
    }
  }
}

并非所有客户端都会在其配置中展开 ${VAR}。如果您的客户端不支持，次优选择是导出变量，让客户端继承它（登录 shell 配置文件、macOS 上的 launchctl setenv、Linux 上的 systemd 单元），然后完全删除 env 块——桥接器会从其继承的环境中读取 PROXYCEPT_API_TOKEN。将文字令牌粘贴到配置文件中也可以，但这是最后的选择。

命令行支持 --token，但不鼓励：参数在进程列表中对该机器上的所有进程可见。

环境变量

每个变量都有对应的标志（--base-url、--url、--token、--timeout、--verbose）。

自托管

PROXYCEPT_BASE_URL=https://proxy.internal.example PROXYCEPT_API_TOKEN=… npx -y @proxycept/mcp

纯文本 http:// 除了回环地址外均被拒绝，因此令牌永远不会通过明文跳转。此包不提供禁用 TLS 验证的标志，将来也不会。

Node 本身有一个——NODE_TLS_REJECT_UNAUTHORIZED=0 会关闭整个进程的证书验证——而桥接器拒绝启动，如果发现该变量针对非回环端点设置，而不是静默继承。如果您遇到该错误，请取消设置该变量（检查您的 shell 配置文件和 MCP 客户端的 env 块）；它几乎总是调试其他东西时留下的，设置后您的令牌将通过路径上任何人都可以读取的连接发送出去。

检查您的设置

PROXYCEPT_API_TOKEN=prx_live_… npx -y @proxycept/mcp --check

它会执行真实的 MCP 握手和真实的 tools/list，然后打印服务器所说的内容：

endpoint: https://proxycept.com/api/mcp
server:   proxycept 1.0.0 (MCP 2025-06-18)
tools:    20 — list_workspaces, list_profiles, …
ok

工具数量来自服务器，而不是来自此包，因此无需在此发布即可更改。写入工具会列出给所有客户端，并在 API 层被拒绝，除非令牌是 read_write——见下文。

退出代码：0 正常 · 1 无法到达服务器或认证失败 · 2 配置错误。

出现问题时

安全属性

• 令牌作为 Authorization: Bearer … 仅发送到配置的源，不会发送到其他地方。重定向到不同源会被拒绝，而不是跟随——凭据永远不会交给您未配置的主机。同源的 307/308 会被跟随（最多 3 跳），因为保留源和方法意味着重新发送凭据不会改变接收方，而且反向代理确实会发出它们；301/302/303 会被拒绝，因为将 POST 重放为 GET 会静默丢弃您的请求。（托管服务器从不重定向。）

• 令牌永远不会被记录，也永远不会返回给您的客户端。 写入 stderr 的每一行以及此桥接器合成到 stdout 的每条错误消息都会经过一个编辑程序，该程序会移除配置的密钥、任何类似 prx_… 令牌的内容以及任何 Bearer … 字符串——包括在 --verbose 模式下，以及服务器在 4xx/5xx 响应体中回显的凭据。最后一种情况很重要，因为 stdout 就是您的 MCP 客户端：它会进入模型的上下文和客户端的日志。永远不会打印堆栈跟踪。每个情况都有对应的测试。

• 协议流永远不会被重写。 编辑仅适用于此桥接器构建的消息，而不适用于服务器自己的 JSON-RPC 负载——篡改这些会破坏您正在调试的流量。捕获流量的编辑是服务器的工作（它在读取路径上应用其屏蔽拒绝列表）。

• 不会写入磁盘。 没有缓存、没有配置文件、没有凭据存储。

• stdout 仅携带协议消息；所有诊断信息都发送到 stderr。

• 零运行时依赖。此包的 npm ls --omit=dev 为空——唯一的供应链是 Node 本身。

开发

cd clients/mcp
npm ci
npm test          # builds, then runs the suite against a fake JSON-RPC server
npm run typecheck

npm run check-package   # asserts the tarball ships every module, the bin, README and LICENSE

布局：src/config.ts（解析 + 验证配置）、src/redact.ts（编辑 + 唯一的日志记录器）、src/http.ts（每条消息一个 POST；SSE、重定向策略、HTTP→JSON-RPC 错误映射）、src/bridge.ts（通用转发循环）、src/stdio.ts（换行符分隔的 JSON 帧）、src/cli.ts（参数、--check、连接）。

针对虚假服务器验证

测试套件针对 test/helpers.js 中的虚假 JSON-RPC HTTP 服务器运行：逐字转发（包括此包从未听说过的方法）、标头形状、Mcp-Session-Id 和协议版本回显、SSE 流式传输、202 通知、HTTP→MCP 错误映射、批处理、重定向策略、会话过期、跨块边界的 NDJSON 帧，以及令牌在所有输出中的缺失。

针对真实 Proxycept 验证

--check 已针对启用了 MCP 服务器的真实 Control API 进行了端到端测试（V4-T66）：真实的 initialize 能力协商、真实的 tools/list（20 个工具），使用只读的 prx_live_ 令牌。其余未知项是生产环境特有的——托管部署是否会发出 Mcp-Session-Id、长时间的工具调用是以 JSON 还是 SSE 返回，以及其 401/403/429 响应体的确切措辞。桥接器是通用的，因此任何这些差异都不需要在此处更改代码；针对 https://proxycept.com 的实时测试是 PUBLISHING.md 的第 5 步。

发布（维护者）

发布是手动操作的，这是有意为之——没有自动发布的 CI 任务，因此即使工作流令牌被泄露，也无法发布处理客户凭证的包。完整的操作手册（组织创建、预检、确切的 npm publish --access public 序列、验证以及弃用路径）位于此目录中的 PUBLISHING.md。该文件不包含在发布的压缩包中。