BlockVectra MCP 服务:面向 AI Agent 的区块链 RPC 与文档工具
BlockVectra Model Context Protocol(MCP,模型上下文协议)服务为开发者与 AI Agent 提供免 key 的区块链 RPC、链状态、价格与文档工具,一行命令接入 Claude Code、Cursor、VS Code、Codex、Gemini CLI、Antigravity 等客户端。
BlockVectra Model Context Protocol(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。
按实际任务比较端点时,可用 RPC 服务商选型清单核对方法成本、历史覆盖和失败恢复。
配置你的 MCP 客户端
按所用客户端查看配置步骤:
连接后,请 Agent 用 {"path":"quickstart","lang":"zh"} 调用 read_doc。这次文档查询无需 BlockVectra API key。
只需要查文档?直接看仅查文档的远程 HTTP 入口。
SDK 示例
用这些独立示例连接 /mcp/docs,搜索文档后读取返回的页面,无需运行模型或提供 BlockVectra 凭据:
Robinhood Chain 上的任务
- 在 Robinhood Chain 上读取数据:选择网络并读取链上数据。
- 在 Robinhood Chain 上开始测试网开发:连接测试网并开始开发。
- 在 Robinhood Chain 上领取测试网代币:申请测试网代币并查询交易回执。
Agent Skill
blockvectra-docs Agent Skill 帮你的编码 Agent 按任务找到对应的 BlockVectra 文档页,并在回答里附上来源。已配置 MCP 时,它先用 search_docs,再用 read_doc;否则通过 HTTP 读取 Markdown 页面。查询文档不需要 BlockVectra 账户或 API key。
这个 Skill 只负责文档,不会替你配置 MCP,也不会执行 RPC 调用、开户或交易;MCP 仍按本页的安装步骤接入。
在你自己的项目里运行下面的命令(需要 Node.js 22.20 或更高版本),并选择你使用的 Agent:
npx --yes skills@1.7.4 add blockvectra/agent-quickstart --skill blockvectra-docs装好后可以直接问:“如何在 Robinhood Chain 上接入?区分主网和测试网,并给出文档来源。”源码见 agent-quickstart。
工具
| 工具 | 用途 | 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 或 Authorization: Bearer …。私钥留在本地;不要把凭据放入工具参数、URL 或对话。
工具参数中的凭据规则
以下规则适用于每个工具,也包括数组内嵌对象,以及输入 schema 允许的额外属性:
- 比较字段名时,仅将 ASCII
A-Z转为a-z,再删除 ASCII_和-。不裁剪空白、不按点拆分,也不折叠 Unicode 字符。 - 所有层级都保留归一化后的名称
apikey、xapikey、authorization、privatekey和secretkey。例如api_key、apiKey、API_KEY、x-api-key、xApiKey、Authorization、privateKey和secret_key。归一化名称key还在参数根对象中保留;嵌套的通用key、publicKey、key_id不因本条规则被保留。 - 保留字段只要存在就拒绝,与值无关,包括
null、空字符串、false、零、数组或对象。 - 每一层的字符串值都会检查区分大小写的 API key 标记
(?:^|[^A-Za-z0-9_-])rgw_[A-Za-z0-9_-]+(?=$|[^A-Za-z0-9_-]),以及大写 PEM 标记-----BEGIN (?:RSA |EC |OPENSSH |ENCRYPTED )?PRIVATE KEY-----。例如合成标记rgw_example会被拒绝;这不表示它是一把有效 API key。 - 不解码不透明值。字符串内的 JSON 不会再解析成对象,但其中的原始字符仍会检查上述标记。普通哈希、公钥或已签名交易十六进制不会仅因长度被判为凭据;单独的
invalid-secret-placeholder也不是识别标记。任何编码形式的真实凭据都不要传入:不透明值被接受不代表可以安全披露。
对于已知工具,省略 arguments 保留工具原有行为;显式提供时必须是对象,null、数组及标量根值会被拒绝。凭据规则先于工具已公开的输入 schema 校验、请求头鉴权和执行。其他属性仍以输入 schema 为准;本规则不把原本允许额外属性的对象改成封闭对象。未知工具名仍返回 JSON-RPC 协议错误。
输入拒绝响应
本地输入拒绝返回 HTTP 200、Cache-Control: no-store,且 result.isError: true。result.structuredContent 必须是只包含 error、reason、message 的对象;文本内容块包含的 JSON 解码后与该对象相等。error 为 invalid_tool_arguments,固定消息不回显传入字段、路径或值。
reason | 重试前的处理 |
|---|---|
invalid_root | 传入对象;工具支持省略参数时也可省略。 |
schema_type | 按已公开输入 schema 修正类型。 |
schema_enum | 使用已公开输入 schema 允许的值。 |
undeclared_property | 删除输入 schema 不允许的属性。 |
credential_field | 删除保留字段;API key 改放客户端 HTTP 请求头,私钥留在本地。 |
credential_value | 删除已识别的凭据材料;API key 改放请求头,私钥留在本地。 |
例如,search_docs 参数 {"query":"RPC","extra":[{"privateKey":null}]} 会在 result.structuredContent 中返回下列对象,文本内容为相等的 JSON:
{
"error": "invalid_tool_arguments",
"reason": "credential_field",
"message": "API keys must never be passed in tool parameters. Configure API keys in the MCP client's x-api-key or Authorization HTTP header; keep private keys local."
}此前按输入错误纯文本做匹配的客户端,应改为读取 structuredContent.error 和 structuredContent.reason。未配置 API key 请求头时调用带 key 工具,可按其 how_to_get_api_key 提示或程序化开户指南继续。
工具执行阶段的请求拒绝
通过上述输入检查及必要的请求头鉴权后,以下工具专属拒绝返回 HTTP 200、Cache-Control: no-store,且 result.isError: true。result.structuredContent 必须是非 null 对象,只包含 error、reason、message。error 为 executor_request_rejected;reason 仅取下表中对应工具允许的值;message 保留该请求原有的拒绝说明。响应恰好包含一个文本内容块,其中 JSON 解码后与该对象相等。
| 工具 | reason 及拒绝条件 |
|---|---|
search_docs | query_required:缺少 query,或去除首尾空白后为空。 |
estimate_usage | method_required:选中的估算行缺少去除首尾空白后非空的 method;calls_per_day_invalid:该行缺少每日调用量,或调用量不是有限的非负整数。适用于单方法估算及 lines 中的各行。 |
get_method_info | method_required:缺少 method,或去除首尾空白后为空。 |
rpc_call | chain_required 或 method_required:缺少对应值,或去除首尾空白后为空;unknown_chain:既有链目录查询完成,但找不到对应的链标识。 |
data_api_get | chain_invalid:去除首尾空白后的 chain 为空,或包含 [A-Za-z0-9_-] 以外的字符;path_invalid:缺少 path、path 为空、以 / 开头、包含 .. 或 //,或包含 ?、#、%。 |
send_raw_transaction | chain_required 或 raw_tx_required:缺少对应值,或去除首尾空白后为空;unknown_chain:既有链目录查询完成,但找不到对应的链标识。 |
例如,get_method_info 参数为 {} 时,structuredContent 和相等的 JSON 文本为:
{
"error": "executor_request_rejected",
"reason": "method_required",
"message": "Missing or invalid 'method' parameter"
}这些拒绝与 invalid_tool_arguments 分开;输入 schema 的类型、enum 和凭据检查仍优先执行。data_api_get 仍先检查 API key 请求头,再执行工具专属检查。链目录获取失败、其他路径字符检查、估算容器错误及其他既有错误保留各自的错误体。每个工具公开的输出 schema 在准确的新拒绝分支之外,保留原有成功、错误及截断结果合同。标记为 executor_request_rejected 的对象必须满足对应工具的完整拒绝 schema,原有分支不能接纳带此标识但形状不合法的对象。
从 Smithery 代理连接迁移
Smithery 已公告:2026-10-31 起停止连接管理及 run.tools / server.smithery.ai 代理连接,其公开的非代理目录保留(公告)。若你现有的 BlockVectra 配置仍使用上述代理域名,请改为 https://docs.blockvectra.com/mcp,并按下方各客户端配置接入。连接并读取文档无需 API key;收费工具沿用原有的请求头认证。可用 read_doc 读取 quickstart,lang 设为 zh 来验证连接。
在各客户端中接入
你可以在常用的开发环境与框架中连接 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、data_api_get、get_account 与 get_deposit_address)时,需在请求头中配置 x-api-key。
仅查文档的远程 HTTP 入口
只需查阅文档时,连接 https://docs.blockvectra.com/mcp/docs。这个入口仅提供 search_docs 和 read_doc,无需 BlockVectra 账户、API key 或本地 Node.js 环境;添加 API key 也不会启用其他工具。
使用 Claude Code 时,运行这一行:
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp/docs这条命令与下面的项目 .mcp.json 二选一即可。命令不会替换或迁移已有的同名服务;如果已配置完整的 /mcp 服务,请按客户端平时的服务管理方式保留想用的那一个。想改用项目文件时,在 .mcp.json 中添加:
{
"mcpServers": {
"blockvectra-docs": {
"type": "http",
"url": "https://docs.blockvectra.com/mcp/docs"
}
}
}其他客户端请使用下方对应的远程 HTTP 配置格式,填入相同 URL。首次读取时,让 Agent 先用任务描述调用 search_docs,再用结果中的 path 和相同的 lang 调用 read_doc。想直接读快速开始,调用 read_doc,参数为 {"path":"quickstart","lang":"zh"}。需要链发现、RPC、Data API、价格或账户工具时,使用完整的 /mcp 入口。
仅查文档的本地 stdio(Node.js 22+)
如果客户端只需要查阅文档,可以运行仅文档模式的本地服务。它只提供 search_docs 和 read_doc 两个工具,通过 HTTP 读取公开文档,不需要 BlockVectra 账号或 API key,也不会转发继承到的 BLOCKVECTRA_API_KEY。RPC、Data API 与账户类工具不属于该模式。
使用下方已公开的 GitHub 0.1.1 发行包;npm 上的 @blockvectra/mcp@0.1.0 不包含该命令。下载发行包和依赖、后续查询文档都需要网络连接。若先下载再本地安装,请先对照发行版的 SHA256SUMS 核验 SHA-256。
{
"mcpServers": {
"blockvectra-docs": {
"command": "npm",
"args": [
"exec",
"--yes",
"--package",
"https://github.com/blockvectra/mcp/releases/download/v0.1.1/blockvectra-mcp-0.1.1.tgz",
"--",
"blockvectra-docs-mcp"
]
}
}
}重启客户端后,确认只列出 search_docs 和 read_doc,再调用 read_doc,把 path 设为 guides/robinhood-chain、lang 设为 zh,即可读取 Robinhood Chain 上的指南。该限制只作用于这条 MCP 连接。需要链目录、RPC 或带 key 工具时,请改用下面的完整桥接;两者选一个配置即可,避免重复添加服务。
本地 stdio(Node.js 22+)
通过 @blockvectra/mcp 本地 stdio 桥接器连接已托管的 BlockVectra MCP 服务(需要 Node.js 22+ 环境,运行仍需网络连接)。
在客户端的 MCP 配置中添加服务:
{
"mcpServers": {
"blockvectra": {
"command": "npx",
"args": ["-y", "@blockvectra/mcp@0.1.0"]
}
}
}初始化、文档工具(read_doc、search_docs、list_docs)以及受支持的公共方法不需要 API key。
调用 Data API 或账户等带 key 工具时,需将 BLOCKVECTRA_API_KEY 设置在启动桥接进程的环境中;如果客户端支持针对单个服务的 env 字段,也可以通过该字段注入本地私密值。桥接器只把该环境变量转换为 x-api-key 请求头,绝不会将 key 放入 CLI 参数、提示词或工具参数中。注意桌面 GUI 客户端可能不会自动继承 shell 环境变量。未配置 key 时调用带 key 工具将提示调用 how_to_get_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 扩展即可快速接入:
gemini extensions install https://github.com/blockvectra/mcp --ref main重启 Gemini CLI,运行 /mcp 确认 blockvectra-docs 服务及其工具已加载。发现类工具无需 API key:可以让 Gemini 调用 list_chains,或用 read_doc 读取 path=quickstart、lang=zh。需要带 key 工具时,见可选鉴权说明。
扩展与下方手工配置二选一,不要同时添加,以免注册重复的服务。
在 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 服务文档。
Antigravity
在 Antigravity 中安装 BlockVectra 文档插件:
agy plugin install https://github.com/blockvectra/mcp插件直接通过远程 HTTP 连接 https://docs.blockvectra.com/mcp,无需本地 npm 桥接。安装后重启 Antigravity,在登录会话中用 /plugin 查看启用状态,用 /mcp 查看工具。验证连接时,让 Antigravity 先调用 list_chains,再用 read_doc 读取 path=quickstart、lang=zh。
连接、文档、链目录、价格和状态工具无需 API key。RPC 调用遵循各链的公开方法策略。Data API 与账户类工具需要你自己的 key,只能放在私密 HTTP 请求头中;不要放进命令参数、工具参数或对话。插件与鉴权细节见 BlockVectra MCP 仓库,官方说明见 Antigravity 插件文档 与 MCP 文档。
goose
goose 可以运行 MCP 服务和打包好的 recipe。安装 goose 并配置模型 provider 后,下载固定版本的 recipe,校验后运行:
curl -fLo blockvectra-docs.json https://raw.githubusercontent.com/blockvectra/mcp/0a7c9173478157523c2a6629ad9fe71e8b29e6c0/recipes/goose-docs.json
goose recipe validate ./blockvectra-docs.json
goose run --recipe ./blockvectra-docs.jsonrecipe 通过 Streamable HTTP 连接 https://docs.blockvectra.com/mcp,只使用 search_docs 和 read_doc。固定任务是在 Robinhood Chain 上搜索主网公共 RPC 配置,再以 lang=en 读取 guides/robinhood-chain。返回内容应说明主网配置,并把测试网 faucet 区分开。recipe 只查询文档,不执行 RPC 调用、不发送交易、不创建账户。
连接和这两个文档工具不需要 BlockVectra 账户或 API key。模型调用由你为 goose 配置的 provider 处理,按其规则计费。
运行失败时,先检查 goose 与 provider 配置以及 goose recipe validate 的输出。
固定版本 recipe 源文件:recipes/goose-docs.json。官方文档:goose recipes。
Hermes Agent
Hermes Agent 原生支持远程 HTTP MCP 服务。在 ~/.hermes/config.yaml 的 mcp_servers 下加入 BlockVectra,合并进已有映射,不要覆盖其它服务:
mcp_servers:
blockvectra:
url: https://docs.blockvectra.com/mcp保存后启动新的 Hermes 会话,让它加载该服务。连接和文档工具不需要 API key;使用带 key 工具时,按本页的 HTTP header 鉴权规则设置 x-api-key 请求头。
已知链时直接给 list_chains 传 chain,例如 robinhood_mainnet,不必枚举全部链。针对具体任务调用 search_docs,再阅读匹配的页面。
官方文档:Hermes Agent 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 客户端配置里设置请求头。
不用 API key 查找并阅读指南
这个示例按顺序发两次 tools/call:先用 search_docs 找到一篇指南,再用 read_doc 读取正文。两次请求都不带 x-api-key。只需要 Python 3,不依赖第三方库。保存为 read_guide.py 后运行 python3 read_guide.py。
import json
import os
import sys
import urllib.request
URL = "https://docs.blockvectra.com/mcp"
LANG = "zh"
USER_AGENT = "BlockVectraDocsExample/1"
if os.environ.get("BLOCKVECTRA_INTERNAL_QA") == "1":
USER_AGENT += " BlockVectraQA/1"
def call(request_id, name, arguments):
body = json.dumps({
"jsonrpc": "2.0",
"id": request_id,
"method": "tools/call",
"params": {"name": name, "arguments": arguments},
}).encode()
req = urllib.request.Request(URL, data=body, headers={
"content-type": "application/json",
"user-agent": USER_AGENT,
})
try:
with urllib.request.urlopen(req, timeout=20) as res:
reply = json.load(res)
except Exception as exc:
sys.exit(f"{name}: request failed ({type(exc).__name__})")
if "error" in reply:
sys.exit(f"{name}: JSON-RPC error {reply['error'].get('code')}")
result = reply.get("result") or {}
if result.get("isError"):
sys.exit(f"{name}: tool error")
return result
found = call(1, "search_docs", {"query": "Robinhood Chain 上 测试网 水龙头", "lang": LANG, "limit": 1})
results = (found.get("structuredContent") or {}).get("results") or []
if not results or not isinstance(results[0].get("path"), str) or not results[0]["path"]:
sys.exit("没有匹配结果:换个关键词,或用 list_docs 浏览。")
path = results[0]["path"]
print("正在读取:", path, file=sys.stderr)
doc = call(2, "read_doc", {"path": path, "lang": LANG})
print(doc["content"][0]["text"])脚本把第一次搜索结果里的 path 原样交给 read_doc,并沿用同一个 lang。path 是相对路径(例如 guides/example),不要加域名、开头的 / 或查询串。指南正文是 Markdown,在 result.content[0].text 里;read_doc 不返回 structuredContent。HTTP 或 JSON-RPC 请求失败、工具返回 isError: true、results 为空时,脚本直接退出,不发第二次请求(结果为空不算错误,但没有可读的内容,请换关键词,或用 list_docs 浏览),也不会重试。示例只读取指南,不会执行指南中的任何命令。
常见问题
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 广播你已在本地签名的交易;服务端不持有也不接触私钥。
调用失败时会怎样?
使用工具结果前,先检查 result.isError,并阅读返回的错误信息。用 explain_error 或错误码参考查看该失败是否计费、是否应重试。
相关页面
- 接入 AI agent:机器可读文件、公开 JSON 接口与选链流程。
- 程序化开户:用钱包签名在无浏览器环境下创建 API key。
- Agent 框架接入配方:ElizaOS、viem、wagmi 与 Coinbase AgentKit。
- 错误码:全部错误及计费与重试规则。
最后更新:
接入 AI agent
为AI Agent接入区块链RPC与文档MCP:先用免key的MCP端点与llms.txt发现可用链与方法,读取文档与定价了解计费规则,再通过开户流程创建key,并用它调用需要鉴权的RPC方法与数据集。
Agent 框架接入配方
为LangChain、ElizaOS、AgentKit等AI Agent与开发框架配置区块链RPC:在.env文件写入端点与钱包私钥,用viem的http()传输层建立连接,免key端点只能读取各链的公开方法,带key后才可访问其余方法与数据集。 包含在 Robinhood Chain 上使用带 API key 的 URL 配置 AgentOS RPC_ROBINHOOD_URL 的方法。