# BlockVectra MCP 服务：面向 AI Agent 的区块链 RPC 与文档工具

> 原文地址: https://docs.blockvectra.com/zh/guides/mcp-server/

BlockVectra MCP 服务（`https://docs.blockvectra.com/mcp`）为开发者与 AI Agent 提供 15 个工具，覆盖区块链 RPC 调用、链状态、价格与文档。连接无需 API key：其中 10 个工具始终免 key，其余工具从客户端请求头读取 `x-api-key`。一行接入：`claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp`

端点为 [MCP 端点](https://docs.blockvectra.com/mcp)（HTTP POST 接收 JSON-RPC 2.0 请求；GET 返回 405），使用 MCP Streamable HTTP 传输，无状态。机器可读文件、公开 JSON 与开户流程见[接入 AI agent](https://docs.blockvectra.com/zh/guides/ai-agents/)。

## 工具

| 工具 | 用途 | API key | 访问类型 |
| --- | --- | --- | --- |
| `read_doc` | 读取文档页的 Markdown 原文。 | 不需要 | 只读 |
| `search_docs` | 按关键词检索文档标题、路径与摘要。 | 不需要 | 只读 |
| `list_chains` | 列出支持的链、参数与方法策略（GET /v1/chains）。 | 不需要 | 只读 |
| `get_status` | 读取实时服务与链状态（GET /v1/status）。 | 不需要 | 只读 |
| `get_pricing` | 读取计算单元权重、免费额度参数与 key 默认限额（GET /v1/plans）。 | 不需要 | 只读 |
| `estimate_usage` | 估算一个或多个方法的计算单元与费用。 | 不需要 | 只读 |
| `how_to_get_api_key` | 返回获取 API key 的步骤与请求鉴权写法。 | 不需要 | 只读 |
| `get_method_info` | 查看方法的可用链、CU 权重与价格。 | 不需要 | 只读 |
| `explain_error` | 查询错误的含义、是否计费、能否重试与恢复方式。 | 不需要 | 只读 |
| `list_docs` | 列出全部文档页的路径与标题。 | 不需要 | 只读 |
| `rpc_call` | 在支持的链上执行只读 JSON-RPC 方法。 | 可选：免 key 仅限该链 public.methods 内的方法 | 只读 |
| `data_api_get` | 对支持的链发起 Data API GET 请求。 | 必需（x-api-key 请求头） | 只读 |
| `get_account` | 读取账户余额、CU 与速率限额（GET /v1/account）。 | 必需（x-api-key 请求头） | 只读 |
| `get_deposit_address` | 读取账户的充值地址、开放网络与代币。 | 必需（x-api-key 请求头） | 只读 |
| `send_raw_transaction` | 广播已签名的原始交易（eth_sendRawTransaction）。 | 可选：免 key 仅限该链 public.methods 内的方法 | 广播已签名交易 |

此表由服务端工具注册表生成，列出 `tools/list` 返回的全部工具。每个工具的入参与返回字段以其 `tools/list` 中的 schema 为准。

### 密钥安全

带 key 工具需要 API key，用于 Data API 请求、账户操作，或链公开方法之外的 RPC 方法。

* **只从请求头读取**：密钥必须且只能通过 MCP 客户端的 HTTP 请求头（`x-api-key: rgw_...` 或 `Authorization: Bearer rgw_...`）传递。
* **严禁写入对话**：绝对不要将 API key、私钥作为工具参数传递，也不要贴入对话记录。工具参数和对话会进入日志与上下文中，存在泄露风险；工具如检测到参数中包含 key 将直接拦截报错。

未配置 key 请求头时调用带 key 工具将返回 `isError: true`，并提示调用 `how_to_get_api_key` 工具或参考[程序化开户指南](https://docs.blockvectra.com/zh/guides/programmatic-signup/)。

## 在各客户端中接入

你可以在常用的开发环境与框架中连接 BlockVectra 文档 MCP 服务（地址为 `https://docs.blockvectra.com/mcp`）。

建议免 key 开始：连接至 MCP 端点，调用 `list_chains`，再通过 `read_doc` 阅读快速上手文档。当需要使用 Data API 或账户类工具时，在客户端的 HTTP 请求头中添加 API key。免 key RPC 访问遵循各链的公开方法策略。

`x-api-key` 请求头为可选项。未配置 API key 时，客户端可使用所有只读文档工具（`read_doc`、`search_docs`、`list_docs`）、链目录查询（`list_chains`）、实时状态（`get_status`）、价格测算（`get_pricing`、`estimate_usage`）、错误解释（`explain_error`）以及公开端点允许的方法。调用带 key 工具（受限方法上的 `rpc_call`、`send_raw_transaction`、`data_api_get`、`get_account` 与 `get_deposit_address`）时，需在请求头中配置 `x-api-key`。

### Claude Code

在终端中使用 CLI 添加 MCP 服务：

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp
```

如需使用带 key 工具，添加 `--header`（或 `-H`）参数配置认证头，并引用环境变量而不是粘贴 key。请用单引号，避免被 shell 提前展开；Claude Code 在启动会话时展开 `${BLOCKVECTRA_API_KEY}`：

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header 'x-api-key: ${BLOCKVECTRA_API_KEY}'
```

等价的项目级 `.mcp.json`（`claude mcp add --scope project` 写出的也是这个内容）：

```json
{
  "mcpServers": {
    "blockvectra-docs": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": { "x-api-key": "${BLOCKVECTRA_API_KEY}" }
    }
  }
}
```

在启动 `claude` 的环境里导出 `BLOCKVECTRA_API_KEY`。项目级 `.mcp.json` 里的服务在该目录首次运行 `claude` 时需要你批准；批准前 `claude mcp list` 显示为 `Pending approval`。

脚本与 CI 中用 `--mcp-config` 传入配置文件，并放行该服务的工具。key 留在环境变量里，请求头由 MCP 客户端自己加，Agent 不需要执行展开 `$BLOCKVECTRA_API_KEY` 的 shell 命令（Claude Code 在非交互模式下会以 `Contains simple_expansion` 拦截这类命令）：

```bash
claude -p "Use rpc_call to run eth_blockNumber on base_mainnet" \
  --mcp-config ./mcp.json --allowedTools "mcp__blockvectra-docs__*"
```

配了 key 时，`rpc_call` 的结果里还会带 `cu_charged` 与 `balance_units`；免 key 调用只返回 JSON-RPC 响应。环境变量没设置时，客户端会把字面文本发出去，服务端返回 `invalid_api_key`（错误码 `-32024`），不会回退到免 key 端点。

官方文档：[Claude Code MCP 文档](https://code.claude.com/docs/en/mcp)。

### Cursor

在 Cursor 的 MCP 配置中添加服务：

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cursor 还支持通过一键深链快速安装。配置对象 `{"url":"https://docs.blockvectra.com/mcp"}` 经 base64 编码后为 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9`，对应的深链地址为：

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9
```

当需要使用 Data API 或账户管理等带 key 工具时，在配置中添加包含 API key 的 `headers` 对象：

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "${env:BLOCKVECTRA_API_KEY}"
      }
    }
  }
}
```

`${env:NAME}` 写法依据 Cursor 官方文档（`url` 与 `headers` 中的变量会被解析），本文未在 Cursor 中实际运行过。配置文件放在 `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局）。

官方文档：[Cursor MCP 文档](https://cursor.com/docs/context/mcp) 与 [Cursor 安装深链文档](https://cursor.com/docs/context/mcp/install-links)。

### VS Code

在 VS Code 中，在 `.vscode/mcp.json` 的顶层 `servers` 键下配置服务，指定 `type: "http"`：

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

当需要使用带 key 工具时，在配置中添加 `headers` 对象：

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

在管理敏感凭据时，VS Code 支持使用输入变量或环境文件引用密钥。此外，也可以通过命令面板的 `MCP: Add Server` 命令添加服务。

官方文档：[VS Code MCP 服务文档](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 与 [VS Code MCP 配置参考](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)。

### Codex

使用 OpenAI Codex CLI 添加服务：

```bash
codex mcp add blockvectra --url https://docs.blockvectra.com/mcp
```

在 `config.toml` 中配置服务 URL：

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
```

当需要使用带 key 工具时，在 `config.toml` 中配置认证请求头：

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }
```

也可以将请求头映射到环境变量：

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }
```

官方文档：[OpenAI Codex CLI MCP 文档](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。

### Gemini CLI

在 Gemini CLI 配置中，在 `mcpServers` 下使用 `httpUrl` 字段添加 Streamable HTTP 服务：

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

当需要使用带 key 工具时，添加包含 API key 的 `headers` 对象：

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

官方文档：[Gemini CLI MCP 服务文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)。

### OpenAI Responses API

在调用 OpenAI Responses API 时，在 `tools` 数组中通过 `type: "mcp"` 传入 MCP 服务：

```bash
OPENAI_API_BASE="https://api.openai.com/v1"
curl "$OPENAI_API_BASE/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'
```

当需要使用带 key 工具时，在工具定义中添加 `headers` 字段：

```json
{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}
```

官方文档：[OpenAI MCP 工具指南](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) 与 [OpenAI Responses API 参考](https://developers.openai.com/api/reference/resources/responses/methods/create)。

### Windsurf

在 Windsurf 中，在 `mcpServers` 下使用 `serverUrl` 字段配置服务：

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

当需要使用带 key 工具时，添加包含 API key 的 `headers` 对象：

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Windsurf 也支持环境变量插值，例如 `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`。

官方文档：[Windsurf MCP 文档](https://docs.devin.ai/desktop/cascade/mcp)。

### Claude 桌面版与 claude.ai

自定义连接器需在界面中添加：

* **claude.ai**：进入 **Customize** > **Connectors**，点击 **+ Add**，选择 **Add custom connector**，并输入 URL：
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude 桌面版**：在账号设置菜单中进入连接器界面完成配置。

输入 URL 连接后，Claude 即可免 key 检索指南、阅读 Markdown 原文、查看支持的链、检查网络状态并进行用量与价格测算。

官方文档：[Claude 自定义连接器指南](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)。

### 检查连接与排错

Claude Code 里 `claude mcp list` 会显示各服务的状态。要确认实际注册了多少工具，可运行一次并读取流式输出里的 `init` 事件，或读调试日志：

```bash
claude -p "say ok" --mcp-config ./mcp.json --output-format stream-json --verbose
claude -p "say ok" --mcp-config ./mcp.json --debug mcp --debug-file mcp-debug.log
```

连接正常时，`init` 事件里 `"status": "connected"`，并带有 `mcp__blockvectra-docs__*` 工具（如 `list_chains`、`rpc_call`）。调试日志里查找包含 `blockvectra-docs` 的行，如 `Successfully connected`、`Failed to fetch tools`。服务显示 `connected` 但没有工具时，看调试日志（`--debug mcp`）里 `Failed to fetch tools` 之后报的原因。要确认服务端本身正常，用下面的 curl 调用。

### 不用客户端直接调用 MCP 端点

端点是基于 HTTP POST 的 JSON-RPC 2.0，任何 HTTP 客户端都能调用：

```bash
curl -s https://docs.blockvectra.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://docs.blockvectra.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"rpc_call","arguments":{"chain":"base_mainnet","method":"eth_blockNumber","params":[]}}}'
```

第一条返回工具列表；第二条的 JSON-RPC 响应在 `result.structuredContent` 里。链标识是 `base_mainnet` 这类 slug，用 `list_chains` 查。带 key 的工具需要 `x-api-key` 请求头；下面这条用环境变量里的 key 读取账户信息：

```bash
curl -s https://docs.blockvectra.com/mcp -H 'content-type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'
```

响应的 `result.structuredContent` 里有 `key_id`、`plan`、`balance_units`、`balance_cu` 和该 key 的速率限制。如果 Agent 通过带权限检查的 shell 执行命令，这种变量展开可能被拦截，此时改在 MCP 客户端配置里设置请求头。

## 常见问题

### BlockVectra MCP 服务需要 API key 吗？

不需要。连接无需 key，15 个工具中有 10 个始终免 key。`rpc_call` 与 `send_raw_transaction` 仅在方法属于该链 `public.methods` 时免 key（用 `list_chains` 查看）。`data_api_get`、`get_account` 与 `get_deposit_address` 需要 `x-api-key` 请求头。

### MCP 服务能创建或吊销 API key 吗？

不能。没有任何工具能创建、列出或吊销 API key。`how_to_get_api_key` 只返回操作步骤；Agent 按[程序化开户](https://docs.blockvectra.com/zh/guides/programmatic-signup/)通过 HTTP 创建 key，个人用户在控制台创建。key 不会经过工具参数传递。

### Agent 能通过 MCP 服务发送交易吗？

能广播，不能签名。`rpc_call` 拒绝 `eth_sendRawTransaction`、`eth_sendTransaction`、`eth_sign`、`personal_*` 等写方法。`send_raw_transaction` 通过 `eth_sendRawTransaction` 广播你已在本地签名的交易；服务端不持有也不接触私钥。

### 调用失败时会怎样？

工具错误返回 `isError: true` 与结构化原因。用 `explain_error` 或[错误码参考](https://docs.blockvectra.com/zh/errors/)查看该失败是否计费、是否应重试。

## 相关页面

* [接入 AI agent](https://docs.blockvectra.com/zh/guides/ai-agents/)：机器可读文件、公开 JSON 接口与选链流程。
* [程序化开户](https://docs.blockvectra.com/zh/guides/programmatic-signup/)：用钱包签名在无浏览器环境下创建 API key。
* [Agent 框架接入配方](https://docs.blockvectra.com/zh/guides/agent-frameworks/)：ElizaOS、viem、wagmi 与 Coinbase AgentKit。
* [错误码](https://docs.blockvectra.com/zh/errors/)：全部错误及计费与重试规则。