Relay

@relaygpu/mcp

Relay 的 MCP 服务。你的 Agent 可以查找 Relay 模型、读取其输入架构、运行模型、轮询长时间任务、上传文件、运行工作流并搜索 Relay 文档，所有操作都可通过 Claude Code、Cursor、VS Code 或 Claude Desktop 完成。它基于 @relaygpu/client 构建。工具是通用的，模型以字符串形式传入，因此添加到 Relay 的模型无需发布新版本即可使用。

连接到托管服务，或在本地运行：

	方式	凭据
托管（Streamable HTTP）	https://mcp.relaygpu.com/mcp，无需安装	X-API-Key: relay_sk_... 请求头，或 Authorization: Bearer <relay key or dashboard JWT>
本地（stdio）	npx -y @relaygpu/mcp（Node ≥ 20）	在其环境中设置 RELAY_API_KEY=relay_sk_...；可选设置 RELAY_BASE_URL（默认值为 https://relaygpu.com）

服务端不会存储你的密钥：托管服务会从每个请求中读取密钥，并仅将其用于该请求；本地服务会从其环境中读取密钥。

安装

Claude Code、Codex、Cursor 和 VS Code 连接到托管服务：无需 Node，也无需 npx。Claude Desktop 目前仅通过 OAuth 接受远程服务，而 v0 尚不支持 OAuth，因此它通过一键安装包使用本地服务。所有客户端也都可以运行本地服务；请参阅本地服务。

Claude Code

在终端中执行，CLI、VS Code 扩展或 JetBrains 扩展均可：

claude mcp add --transport http --scope user relay https://mcp.relaygpu.com/mcp --header "X-API-Key: relay_sk_..."

--scope user 会使其在每个项目中都可用；不加此参数时，该服务仅存在于你运行命令的目录中。在新会话中使用 /mcp 检查。如果终端提示 command not found: claude，说明已安装扩展，但尚未安装 CLI：使用 curl -fsSL https://claude.ai/install.sh | bash（或 npm install -g @anthropic-ai/claude-code）进行安装。

Codex

Codex 会将密钥作为 Bearer 令牌从环境变量中传入，因此密钥不会写入 config.toml。在 shell 配置文件中设置 RELAY_API_KEY，然后：

codex mcp add relay --url https://mcp.relaygpu.com/mcp --bearer-token-env-var RELAY_API_KEY

Cursor

此按钮会安装下方的配置项，其中密钥为占位符；之后请在 Cursor 的 MCP 设置中替换 relay_sk_...。手动配置：~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。

{
  "mcpServers": {
    "relay": {
      "url": "https://mcp.relaygpu.com/mcp",
      "headers": { "X-API-Key": "relay_sk_..." }
    }
  }
}

VS Code（Copilot Agent 模式）

此操作会为 VS Code 自带的 Agent（Copilot Chat）安装服务。在 VS Code 中使用 Claude Code？请改用 Claude Code 命令：Claude Code 扩展不会读取 VS Code 的 MCP 配置。

VS Code 会提示你输入一次密钥，并将其保存在机密存储中。手动配置：在 .vscode/mcp.json 中设置（单个工作区），或使用 MCP: Open User Configuration（所有工作区）：

{
  "inputs": [{ "type": "promptString", "id": "relay-key", "description": "Relay API key (relay_sk_...)", "password": true }],
  "servers": {
    "relay": {
      "type": "http",
      "url": "https://mcp.relaygpu.com/mcp",
      "headers": { "X-API-Key": "${input:relay-key}" }
    }
  }
}

Claude Desktop

1. 下载 relay.mcpb。
2. 双击该文件。Claude Desktop 会打开安装对话框：点击 Install。
3. 扩展安装后默认处于关闭状态。打开 Settings → Extensions → Relay → Configure。
4. 粘贴你的 Relay 密钥并点击 Save。密钥会保存在 Claude Desktop 的安全存储中。
5. 开启 Relay。

此软件包使用 Claude Desktop 内置的 Node 运行，无需安装其他内容。get_credits 和 get_usage 会读取账户信息，因此需要使用仪表板 JWT 或自定义层级超级密钥，而不能使用普通密钥；其他所有工具都可以使用普通密钥。

也可以手动配置：Settings → Developer → Edit Config 会在默认编辑器中打开 claude_desktop_config.json。在顶层添加下面的代码块，保存后退出 Claude Desktop（⌘Q）并重新打开：

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relaygpu/mcp"],
      "env": { "RELAY_API_KEY": "relay_sk_..." }
    }
  }
}

本地服务（stdio）

任何客户端也可以改为在你的计算机上运行该服务；客户端所能访问的 PATH 中需要有 Node 20 或更新版本（参见故障排除）。

claude mcp add relay --scope user --env RELAY_API_KEY=relay_sk_... -- npx -y @relaygpu/mcp
codex mcp add relay --env RELAY_API_KEY=relay_sk_... -- npx -y @relaygpu/mcp

Cursor（~/.cursor/mcp.json）和 VS Code 使用与上方 Claude Desktop 代码块相同的 command / args / env 条目；VS Code 还会添加 "type": "stdio"，并将其列在 "servers" 下。

可直接复制的文件位于 examples/。

故障排除

• “Server disconnected”、“spawn npx ENOENT”或“Executable not found: npx”（Claude Desktop、Cursor）。从 Dock 或“开始”菜单打开的应用不会加载你的 shell 配置文件，因此使用 nvm、Volta 或 Homebrew 安装的 Node 不在它们的 PATH 中。请使用 Claude Desktop 软件包，或在 "command" 中填写完整路径：在终端运行 which npx 并粘贴结果（例如 /Users/you/.nvm/versions/node/v22.22.0/bin/npx）。
• TypeError: Relay: no global fetch：客户端启动的是 Node 16 或更旧版本。请安装 Node 20 或更新版本，或将 "command" 指向较新版本的 npx。
• Windows：如果客户端无法启动 npx，请使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@relaygpu/mcp"]。
• 首次启动需要几秒钟：npx 会下载一次软件包（约 5 s）；之后的启动约需 1 s。

工具

标记为 keyless 的工具在本地服务上无需凭据即可使用。其他工具属于计费或账户工具，需要凭据。启用了 OAuth 的托管服务（参见 自托管）不会接受任何没有凭据的请求，包括无密钥工具。

工具	功能	示例
search_models keyless	按标签和/或文本查找模型；image-to-image 还会列出所有接受输入图像的图像模型（accepts: ["image"]）	“查找一个来自 Kling 的文本转视频模型” → {tag: "text-to-video", query: "kling"}
get_model keyless	获取一个模型的路由、请求架构、示例、定价和状态	{model: "Qwen/qwen-image"}
get_pricing keyless	获取一个或所有模型的公开价格，包括 media_storage SKU	{model: "KlingTeam/v3-T2V"}
estimate_cost keyless	根据公开价格表估算费用（不是账单）	{model: "KlingTeam/v3-T2V", usage: {duration_seconds: 5, quality_mode: "std"}}
run_model	按名称运行任意模型，并等待最多 45 s	{model: "Qwen/qwen-image", input: {prompt: "a red fox", size: "512x512"}}
check_task keyless	轮询任务（最多等待 30 s）	{task_id: "direct:…", wait_seconds: 30}
upload_file	托管文件并获取可用于任何 *_url 输入（或图像编辑器的 image）的 URL；或者为托管服务上的本地文件生成一次性上传槽位	{path: "./clip.mp4", retention: "relay1d"} · {slot: true}
list_workflows	列出工作流模板	“我可以运行哪些工作流？”
run_workflow	启动工作流运行，并等待最多 45 s	{workflow_id: "script-voiceover", inputs: {messages: [{role: "user", content: "a lighthouse at dusk"}], voice: "Cherry"}}
check_workflow_run keyless	轮询运行（最多等待 30 s）	{run_id: "…", wait_seconds: 30}
cancel_workflow_run	取消仍在进行的运行	{run_id: "…"}
get_credits	查询积分余额、促销和消耗情况（JWT 或自定义层级超级密钥）	“我还剩多少积分？”
get_usage	使用情况分析（JWT 或自定义层级超级密钥）	{period: "7d"}
search_docs keyless	搜索 Relay 文档	{query: "idempotency key"}

本地文件

托管服务无法读取你电脑上的文件。不同客户端将本地文件传给模型的方式如下：

客户端	本地文件 → 模型
Claude Code、Cursor、VS Code、Codex（托管服务）	upload_file({slot: true}) 会返回一行 curl 命令；Agent 使用文件路径在你的 shell 中运行该命令（密钥不会进入 shell、仅可使用一次、有效期为 10 分钟），然后命令会输出文件的 url；将该 url 传给 run_model（例如作为 image）。
claude.ai、Claude Desktop、ChatGPT	upload_file({slot: true}) 会返回一个链接：在浏览器中打开该链接，选择照片，然后将页面显示的链接粘贴回聊天中；模型会将其传给 run_model。密钥不会离开聊天、仅可使用一次、有效期为 10 分钟。也可以使用文件的公开 URL。
本地服务（stdio），任何客户端	upload_file({path: "./photo.png"}) 会上传文件并返回其 url。

图像编辑器：search_models({tag: "image-to-image"}) 会列出所有接受输入图像的图像模型，每个模型都标有 accepts: ["image"]。

备注

• 身份验证。 在本地服务以及未启用 OAuth 的托管服务上，tools/list 和无需密钥的工具无需凭据即可响应。启用了 OAuth 的托管服务会对每个不带凭据的 /mcp 请求返回 401 和 WWW-Authenticate: Bearer resource_metadata="…", scope="relay"，客户端通过这种方式启动“连接 Relay”登录流程；X-API-Key 和 Authorization: Bearer <relay key or dashboard JWT> 在此仍然有效。调用计费工具时若未提供凭据，会返回 MISSING_CREDENTIALS 工具错误，并指出需要设置的内容：X-API-Key 请求头（托管服务）或 RELAY_API_KEY（stdio）。Relay 返回的错误会作为工具错误返回，其中包含错误类别、code、requestId 和服务器的详细信息。你的密钥不会出现在工具结果或日志行中。
• 长任务。 run_model 最多等待 45 s（wait_seconds，0–45）。如果任务仍在运行，它会返回 task_id 和提示“请勿重新提交：使用此 task_id 调用 check_task”。每次提交都会携带 Idempotency-Key，因此重试不会重复计费。如果你的 Agent 可能再次发送相同的提交，请传入自定义的 idempotency_key。从 0.1.7 开始，所有输入架构接受 async 的模型（图像、视频、音频）都会以任务形式提交，因此长时间运行的图像任务会返回 task_id，不会返回 524；聊天模型仍会直接内联响应。
• 过期时间。 每个结果链接都会注明其过期时间：“除非设置了 store_output，否则在完成后 1 h 过期”。若要延长结果的保留时间，请传入 store_output，并使用 get_pricing 返回的 media_storage SKU（例如 relay7d）。该 SKU 会按文件收取费用。
• 图像链接。 返回 base64 的图像路由（Gemini、gpt-image、FLUX-2-pro）也会返回 Relay 自有链接（urls）；服务器会用这些链接替代 base64，保留 1 h 或 store_output 指定的时长。若结果包含 base64，但没有 Relay 链接，则会通过 /v2/files 上传（保留时长为 store_output 指定的时长，否则为 relay1h；在每日配额内免费），并返回 URL 和 file_id。图像内容块默认关闭：传入 inline_images: true 即可启用，该选项适用于不超过 1 MB 的图像。
• 上传。 在 stdio 模式下，upload_file 会流式上传最大 100 MB 的本地 path。托管服务无法读取你的磁盘：请使用 slot: true（见本地文件）、base64（最大 4 MB）或公开的 url。默认保留时长为 relay1h。

自托管

docker build -t relaygpu-mcp .
docker run -p 2300:2300 -e PORT=2300 -e RELAY_BASE_URL=https://relaygpu.com relaygpu-mcp

服务器监听 PORT（默认值为 2300），并通过 RELAY_BASE_URL 调用 Relay。端点：

• POST /mcp：Streamable HTTP，无状态。
• GET /healthz：返回 {status, version}。
• GET /metrics：Prometheus 文本，包含 mcp_tool_calls_total{tool,outcome} 和 mcp_tool_seconds{tool}。
• GET /.well-known/mcp/server-card.json：服务器及其工具。
• GET /.well-known/oauth-protected-resource（以及 …/mcp）：RFC 9728 受保护资源元数据，仅在启用 OAuth 时提供。

OAuth（“Connect Relay”）

当 OAUTH_ISSUER 和 MCP_RESOURCE_URL 均已设置时，OAuth 会启用；任一变量未设置时，服务的行为与上述相同（没有元数据路由，无需凭据即可调用无需密钥的工具）。所有三个变量都属于 MCP 应用，并在启动时读取一次：

变量	生产环境	预发布环境（VPN）	备注
OAUTH_ISSUER	https://relaygpu.com	https://staging-back-c54ef4a.opengpu.network	Relay 的授权服务器；JWKS 从 {issuer}/v2/oauth/jwks 读取，交换请求发送至 {issuer}/v2/oauth/token
MCP_RESOURCE_URL	https://mcp.relaygpu.com/mcp	http://relay-mcp-staging.internal.opengpu.network/mcp	此服务的公共 /mcp URL：访问令牌的 aud 必须与其相同，元数据 URL 则为其源站加上 /.well-known/oauth-protected-resource
OAUTH_MCP_CLIENT_SECRET	密钥	密钥	relay-mcp 客户端的密钥：必须与同一环境中 Relay 的 OAUTH_MCP_CLIENT_SECRET 值相同，不得跨环境共享。未设置时，所有交换都会失败（503）

如果 Bearer 值是由 OAUTH_ISSUER 签发的 JWT，则该值为访问令牌：服务会验证该令牌（使用签发方的 JWKS 验证 ES256、aud 和 exp，允许 60 秒时钟偏差），并将其发送至 Relay 交换为有效期为 5 分钟的 Relay 凭据；该凭据会按令牌哈希缓存在内存中，直到过期前 30 秒。无效、过期或已撤销的令牌会返回 401 和 WWW-Authenticate: Bearer error="invalid_token", …；无法连接授权服务器时会返回 503。令牌、凭据和密钥绝不会写入日志。

日志以 JSON 行格式输出到 stderr，默认记录 WARNING 及以上级别（LOG_LEVEL）。不使用 Docker 时，运行 npm ci && npm run build && node dist/http.js。

许可证

MIT