内容
# 中继平面MCP服务器
> 在多步骤工作流程中减少90%以上的AI上下文使用量
中继平面（RelayPlane）将工作流程引擎中的中间结果保存起来，而不是通过您的上下文窗口传递它们——从而节省令牌并降低成本。
## 目录
- [快速入门](#快速入门)
- [安装选项](#安装选项)
- [模型ID](#模型ID)
- [可用工具](#可用工具)
- [预算保护](#预算保护)
- [预建技能](#预建技能)
- [配置](#配置)
- [故障排除](#故障排除)
---
## 快速入门
### 1. 使用API密钥安装（推荐）
```bash
claude mcp add relayplane \
-e OPENAI_API_KEY=sk-... \
-e ANTHROPIC_API_KEY=sk-ant-... \
-- npx @relayplane/mcp-server
```
### 2. 重启Claude代码
**重要：** 在添加MCP服务器后，您必须完全重启Claude代码。`/mcp`命令仅重新连接，不会重新加载环境变量。
### 3. 测试连接
询问Claude： *"使用relay_models_list显示已配置的提供商"*
模型应显示`configured: true`，表示提供商具有有效的API密钥。
---
## 安装选项
### 选项A：内联API密钥（最简单）
```bash
claude mcp add relayplane \
-e OPENAI_API_KEY=sk-proj-... \
-e ANTHROPIC_API_KEY=sk-ant-... \
-e GOOGLE_API_KEY=AIza... \
-e XAI_API_KEY=xai-... \
-- npx @relayplane/mcp-server
```
### 选项B：Shell环境变量
首先，添加到您的Shell配置文件（`~/.zshrc`或`~/.bashrc`）：
```bash
export OPENAI_API_KEY=sk-proj-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...
export XAI_API_KEY=xai-...
```
然后，加载并安装：
```bash
source ~/.zshrc
claude mcp add relayplane -- npx @relayplane/mcp-server
```
### 选项C：手动配置
直接编辑`~/.claude.json`:
```json
{
"projects": {
"/your/project/path": {
"mcpServers": {
"relayplane": {
"type": "stdio",
"command": "npx",
"args": ["@relayplane/mcp-server"],
"env": {
"OPENAI_API_KEY": "sk-proj-...",
"ANTHROPIC_API_KEY": "sk-ant-...",
"GOOGLE_API_KEY": "AIza...",
"XAI_API_KEY": "xai-..."
}
}
}
}
}
}
```
> **警告：** `env`字段必须包含实际的API密钥，而不是像`${OPENAI_API_KEY}`这样的变量引用。在MCP配置文件中不支持变量替换。
---
## 模型ID
> **重要：** 始终检查 https://relayplane.com/docs/providers 以获取最新的模型ID。`relay_models_list`工具可能会返回过时的信息。
### OpenAI — 前缀：`openai:`
| 模型ID | 最适合 |
|-------------|-----------------------------|
| gpt-5.2 | 最新旗舰，1M上下文 |
| gpt-5-mini | 成本高效，快速 |
| gpt-5-nano | 超快速，最小成本 |
| o3-mini | 推理任务 |
### Anthropic — 前缀：`anthropic:`
| 模型ID | 最适合 |
|----------------------------|-----------------------------------|
| claude-opus-4-5-20251101 | 最智能，复杂任务 |
| claude-sonnet-4-5-20250929 | 最佳编码，最强代理 |
| claude-haiku-4-5-20251001 | 快速，大量任务 |
| claude-3-5-haiku-20241022 | 快速，经济（旧版） |
### Google — 前缀：`google:`
| 模型ID | 最适合 |
|------------------|--------------------------|
| gemini-3-pro | 最强大的多模态 |
| gemini-3-flash | 快速多模态 |
| gemini-2.5-flash | 经济 |
### xAI — 前缀：`xai:`
| 模型ID | 最适合 |
|------------|-------------------------------|
| grok-beta | 最新旗舰，256K上下文 |
### 示例用法
```json
{
"name": "my-step",
"model": "openai:gpt-5.2",
"prompt": "分析这些数据..."
}
```
---
## 可用工具
| 工具 | 目的 | 成本 |
|-------------------------|--------------------------|-----------|
| relay_run | 单个提示执行 | 按令牌计费 |
| relay_workflow_run | 多步骤编排 | 按令牌计费 |
| relay_workflow_validate | 验证DAG结构 | 免费 |
| relay_skills_list | 列出预建模式 | 免费 |
| relay_models_list | 列出可用模型 | 免费 |
| relay_runs_list | 查看最近运行 | 免费 |
| relay_run_get | 获取运行详情 | 免费 |
---
## 预算保护
默认防护措施（可通过CLI标志自定义）：
| 限制 | 默认值 | 标志 |
|-----------------|---------|------------------------|
| 每日支出 | $5.00 | --max-daily-cost |
| 单次调用成本 | $0.50 | --max-single-call-cost |
| 每小时请求 | 100 | --max-calls-per-hour |
中继平面是BYOK（自带密钥）——我们不收取API使用费用。成本仅反映您的提供商账单。
---
## 预建技能
使用`relay_skills_list`查看可用的工作流程模板：
| 技能 | 上下文减少 | 用例 |
|-------------------|-------------------|---------------------------------------|
| invoice-processor | 97% | 提取，验证，汇总发票 |
| content-pipeline | 90% | 生成和优化内容 |
| lead-enrichment | 80% | 丰富联系人数据 |
---
## 配置
### 持久化配置文件
创建`~/.relayplane/mcp-config.json`:
```json
{
"codegenOutDir": "./servers/relayplane",
"maxDailyCostUsd": 10.00,
"maxSingleCallCostUsd": 1.00,
"maxCallsPerHour": 200
}
```
> **注意：** API密钥应通过环境变量或Claude Code MCP的`env`字段传递——不要存储在此配置文件中。
---
## 故障排除
### "提供商未配置"错误
```
提供商"openai"（步骤"extract"）未配置。
请设置OPENAI_API_KEY环境变量。
```
**原因：**
1. API密钥未传递给MCP服务器
2. 配置更改后未重启Claude Code
**解决方案：**
1. 检查`~/.claude.json`中的MCP配置：
```json
"relayplane": {
"env": {
"OPENAI_API_KEY": "sk-..." // 必须是实际密钥，而不是${VAR}
}
}
```
2. 完全重启Claude Code（使用`Ctrl+C`退出，重新启动）
3. 验证配置：
询问Claude： *"使用relay_models_list并检查哪些显示为configured: true"*
---
### 模型未找到（404错误）
```
Anthropic API错误：404 - 模型：claude-3-5-sonnet-20241022
```
**原因：** 模型ID已过时或不正确。
**解决方案：** 在 https://relayplane.com/docs/providers 查看当前模型ID
常见修复：
- 使用`claude-sonnet-4-5-20250929`获取最新的Claude Sonnet
- 使用`gpt-5.2`获取最新的OpenAI旗舰模型
---
### 配置更改不生效
**原因：** `/mcp`重新连接不会重新加载环境变量。
**解决方案：** 完全重启Claude Code：
1. 使用`Ctrl+C`退出
2. 重新启动`claude`
3. 运行`/mcp`验证连接
---
### 工作流程验证通过但执行失败
**原因：** `relay_workflow_validate`仅检查DAG结构，不检查：
- API密钥有效性
- 模型可用性
- 模式兼容性
**解决方案：** 首先使用简单的`relay_run`进行测试：
```
使用模型"openai:gpt-5.2"和提示"说你好"
```
---
## 快速测试
设置完成后，验证一切正常：
```
使用relay_workflow_run创建发票处理器：
- 步骤1（提取）：使用openai:gpt-5.2提取供应商，总金额来自发票
- 步骤2（验证）：使用anthropic:claude-haiku-4-5-20251001验证数学
输入："来自Acme Corp的发票，总金额：$500"
```
预期：两个步骤都成功完成，并带有结构化输出。
---
## 支持
- **文档：** https://relayplane.com/docs
- **模型ID：** https://relayplane.com/docs/providers
- **问题：** https://github.com/RelayPlane/mcp-server/issues
---
## 许可证
MIT
