BlockVectra MCP server

Remote Model Context Protocol server for BlockVectra: multi-chain EVM JSON-RPC, indexed Data API, docs, CU pricing and status. Documentation, discovery, pricing and status need no API key. Keyless RPC depends on each chain's public method policy; indexed Data API and account tools require your own BlockVectra API key.

中文

Robinhood Chain mainnet and testnet tasks

Use the chain RPC guide for mainnet public read-only RPC tasks. Use the testnet starter and faucet guide for testnet tasks. Mainnet public reads do not require claiming testnet tokens first.

Connect to https://docs.blockvectra.com/mcp without headers for documentation and discovery. Robinhood Chain public endpoints allow supported RPC reads without a key; methods outside the public policy require an API key. Faucet claims require x-api-key. HTTP 202 means accepted; check the transaction receipt for on-chain inclusion (status: "0x1"), which is not finality.

Local stdio bridge

Use Node.js 22 or newer to run the MIT-licensed stdio bridge:

npx --yes @blockvectra/[email protected]

Configure a stdio client:

{
  "mcpServers": {
    "blockvectra-docs": {
      "command": "npx",
      "args": ["--yes", "@blockvectra/[email protected]"]
    }
  }
}

For a source checkout, run npm ci, then use node with the absolute path to src/cli.js instead.

The CLI always bridges to https://docs.blockvectra.com/mcp; it accepts no command-line arguments. Optionally supply BLOCKVECTRA_API_KEY through the child process environment or your client's private environment settings. It is forwarded only as x-api-key. Never put a key in CLI arguments, tool arguments, or chat; never supply private keys.

The bridge connects the official StreamableHTTPClientTransport and StdioServerTransport directly, without rebuilding capabilities or tools. It preserves initialize parameters/results, capabilities, instructions, protocolVersion, tool results, JSON-RPC errors, notifications and bidirectional requests at the JSON message level (not byte formatting). After a successful initialize response, it sets the HTTP transport's negotiated protocol version before forwarding that response. stdout contains MCP messages only; stderr uses fixed diagnostics without SDK error text. EOF, SIGINT and SIGTERM close both transports; transport failures close the bridge with exit code 1. HTTP/SSE behavior, parsing and reconnection remain SDK behavior.

Dependencies are pinned to official @modelcontextprotocol/client and @modelcontextprotocol/server 2.3.1, whose published package exports and source provide these transports and require Node >=20. See the official SDK repository/releases and connection documentation. As of 2026-10-13, Node's official release table lists Node 20 as EOL and Node 22 as LTS, so this package requires Node >=22.

Local verification: npm test runs only the serial mock HTTP/real stdio subprocess tests; npm pack --dry-run checks the package contents. No build is required.

Install in one step

Server URL (Streamable HTTP, no key needed): https://docs.blockvectra.com/mcp

The Cursor config value is the base64 of {"url":"https://docs.blockvectra.com/mcp"}. The VS Code link is the URL-encoded JSON server configuration.

The plugin is described by .claude-plugin/marketplace.json and .claude-plugin/plugin.json. It installs the blockvectra MCP server from .mcp.json and, as a dependency, the blockvectra-rpc skill from blockvectra/skills.

• Endpoint: https://docs.blockvectra.com/mcp (Streamable HTTP, stateless)
• Auth: optional x-api-key header (a BlockVectra API key). Authorization: Bearer <key> is also accepted. Without a key you can use the documentation, chain, pricing and status tools, and the JSON-RPC methods that a chain's public endpoint allows.
• Never put API keys or private keys in tool arguments or chat; the server reads the key only from HTTP headers.

Chains, prices and limits change, so this README does not list them. Read them live:

• Supported chains: GET https://api.blockvectra.com/v1/chains
• Plans, prices and limits: GET https://console-api.blockvectra.com/v1/plans
• Service status: GET https://api.blockvectra.com/v1/status

More: BlockVectra for agents and AI agents guide.

Gemini CLI extension

The extension connects to https://docs.blockvectra.com/mcp directly over remote Streamable HTTP. You do not need the local stdio bridge or npm.

After installing, restart Gemini CLI and run /mcp to inspect the available tools. Try list_chains, then call read_doc with path=quickstart and lang=en.

Optional authentication

The extension is keyless by default: documentation, discovery, pricing and status stay keyless; RPC follows each chain's public method policy; indexed data and account tools need your own BlockVectra API key. Never put a key in argv, tool arguments, chat or version control, and do not export a literal key into shell history. Make BLOCKVECTRA_API_KEY available in Gemini's process environment before launch, using your existing private secret manager or private launch environment; a .gemini/.env file alone is not sufficient.

To send the key as a header, merge this into your user ~/.gemini/settings.json without replacing other settings:

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

This user-scope entry overrides the extension's server of the same name. Restart Gemini CLI after configuring it. gemini mcp list or /mcp only checks connectivity, not successful account or data authorization; to verify authentication, intentionally call the read-only get_account tool and keep the returned account data private.

Tested with official Gemini CLI 0.65.0 against a local mock with a synthetic key; this verifies client configuration and header transmission, not live keyed tool behavior. See Gemini CLI MCP custom headers.

Tools

This table reflects the server currently live at https://docs.blockvectra.com/mcp. Call tools/list for the authoritative list.

Note: get_deposit_address and the other keyed tools return an error that points to how_to_get_api_key when called without a key.

Use in Cursor / Cline

The keyless Cursor configuration is in .mcp.json, referenced by the Cursor plugin manifest. For Cline's Streamable HTTP setup and optional x-api-key headers, follow llms-install.md. Start without headers: call list_chains, then read_doc with {"path":"quickstart","lang":"en"}.

Connect a client

Each snippet below follows the client's own documentation. Add the optional key header as that documentation describes for custom headers.

Claude Code

claude mcp add --transport http blockvectra https://docs.blockvectra.com/mcp
# For an optional key, use private environment-backed header settings;
# see the Codex env_http_headers example below. Never pass a key as a CLI argument.

Cursor (mcp.json)

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

VS Code (.vscode/mcp.json)

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

Codex (~/.codex/config.toml)

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
# optional: read the key from an environment variable
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }

Registry

server.json describes this server for the official MCP Registry under the name com.blockvectra/docs. Publishing is a manual workflow (.github/workflows/publish.yml).

License

MIT