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

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 端点（HTTP POST 接收 JSON-RPC 2.0 请求；GET 返回 405），使用 MCP Streamable HTTP 传输，无状态。机器可读文件、公开 JSON 与开户流程见接入 AI agent。

工具

此表由服务端工具注册表生成，列出 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 工具或参考程序化开户指南。

在各客户端中接入

你可以在常用的开发环境与框架中连接 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 服务：

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

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

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 写出的也是这个内容）：

{
  "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 拦截这类命令）：

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 文档。

Cursor

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

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

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

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

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

{
  "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 文档 与 Cursor 安装深链文档。

VS Code

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

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

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

{
  "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 服务文档 与 VS Code MCP 配置参考。

Codex

使用 OpenAI Codex CLI 添加服务：

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

在 config.toml 中配置服务 URL：

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

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

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

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

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

官方文档：OpenAI Codex CLI MCP 文档。

Gemini CLI

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

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

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

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

官方文档：Gemini CLI MCP 服务文档。

OpenAI Responses API

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

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 字段：

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

官方文档：OpenAI MCP 工具指南 与 OpenAI Responses API 参考。

Windsurf

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

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

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

{
  "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 文档。

Claude 桌面版与 claude.ai

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

• claude.ai：进入 Customize > Connectors，点击 + Add，选择 Add custom connector，并输入 URL：

  复制文字

  https://docs.blockvectra.com/mcp

• Claude 桌面版：在账号设置菜单中进入连接器界面完成配置。

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

官方文档：Claude 自定义连接器指南。

检查连接与排错

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

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 客户端都能调用：

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 读取账户信息：

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 按程序化开户通过 HTTP 创建 key，个人用户在控制台创建。key 不会经过工具参数传递。

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

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

调用失败时会怎样？

工具错误返回 isError: true 与结构化原因。用 explain_error 或错误码参考查看该失败是否计费、是否应重试。

相关页面

• 接入 AI agent：机器可读文件、公开 JSON 接口与选链流程。
• 程序化开户：用钱包签名在无浏览器环境下创建 API key。
• Agent 框架接入配方：ElizaOS、viem、wagmi 与 Coinbase AgentKit。
• 错误码：全部错误及计费与重试规则。