# BlockVectra MCP server: blockchain RPC and docs tools for AI agents > Original page: https://docs.blockvectra.com/en/guides/mcp-server/ The BlockVectra MCP server at `https://docs.blockvectra.com/mcp` gives developers and AI agents 15 tools for blockchain RPC calls, chain status, pricing and docs. It needs no API key to connect: 10 tools never need one; the others use `x-api-key` from your client headers. Install in one line: `claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp` The endpoint is [MCP endpoint](https://docs.blockvectra.com/mcp) (HTTP POST receiving JSON-RPC 2.0; GET returns 405), served over MCP Streamable HTTP and stateless. For the HTTP files, public JSON and the sign-up flow around it, see [Connect AI agents](https://docs.blockvectra.com/en/guides/ai-agents/). ## Tools | Tool | What it does | API key | Access | | --- | --- | --- | --- | | `read_doc` | Read a documentation page as Markdown. | Not needed | Read-only | | `search_docs` | Search documentation titles, paths and summaries. | Not needed | Read-only | | `list_chains` | List supported chains, parameters and method policies (GET /v1/chains). | Not needed | Read-only | | `get_status` | Read live service and chain status (GET /v1/status). | Not needed | Read-only | | `get_pricing` | Read Compute Unit weights, Free Plan parameters and key defaults (GET /v1/plans). | Not needed | Read-only | | `estimate_usage` | Estimate Compute Units and cost for one or more methods. | Not needed | Read-only | | `how_to_get_api_key` | Return the steps for getting an API key and the request authentication shapes. | Not needed | Read-only | | `get_method_info` | Show a method's chain availability, CU weight and price. | Not needed | Read-only | | `explain_error` | Look up an error's meaning, billing, retryability and recovery. | Not needed | Read-only | | `list_docs` | List every documentation page with its path and title. | Not needed | Read-only | | `rpc_call` | Run a read-only JSON-RPC method on a supported chain. | Optional: keyless only for methods in the chain's public.methods | Read-only | | `data_api_get` | Send a GET request to the Data API of a supported chain. | Required (x-api-key header) | Read-only | | `get_account` | Read account balance, CU and rate limits (GET /v1/account). | Required (x-api-key header) | Read-only | | `get_deposit_address` | Read the account's deposit address, open networks and tokens. | Required (x-api-key header) | Read-only | | `send_raw_transaction` | Broadcast an already signed raw transaction (eth_sendRawTransaction). | Optional: keyless only for methods in the chain's public.methods | Broadcasts a signed transaction | This table is generated from the server's tool registry, so it lists every tool `tools/list` returns. Each tool takes the arguments and returns the fields described in its own `tools/list` schema. ### API key security Keyed tools need an API key to run Data API requests, account operations, or RPC methods outside a chain's public methods. * **Read strictly from headers**: The API key is read solely from MCP client HTTP request headers (`x-api-key: rgw_...` or `Authorization: Bearer rgw_...`). * **Never put keys in chat**: Never pass API keys or private keys in tool arguments or paste them into chat. Tool arguments and chat history enter conversation logs and contexts; passing keys in arguments will be rejected. If called without an API key header, keyed tools return `isError: true` and direct the agent to `how_to_get_api_key` and the [programmatic sign-up guide](https://docs.blockvectra.com/en/guides/programmatic-signup/). ## Install in your client You can connect to the BlockVectra documentation MCP server at `https://docs.blockvectra.com/mcp` across common development environments and frameworks. Start without an API key. Connect to the MCP endpoint, call list\_chains, then read quickstart with read\_doc. Add an API key in your client's HTTP headers when you need Data API or account tools. Keyless RPC access follows each chain's public method policy. The `x-api-key` header is optional. Without an API key, clients can use all read-only documentation tools (`read_doc`, `search_docs`, `list_docs`), chain discovery (`list_chains`), live status (`get_status`), pricing estimation (`get_pricing`, `estimate_usage`), error explanations (`explain_error`), and methods permitted on public endpoints. When using keyed tools (`rpc_call` on restricted methods, `send_raw_transaction`, `data_api_get`, `get_account`, and `get_deposit_address`), configure the `x-api-key` header with your API key. ### Claude Code Connect to the MCP server using the CLI: ```bash claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp ``` To include an optional API key for authenticated tools, pass the `--header` (or `-H`) option and reference an environment variable instead of pasting the key. Use single quotes so your shell does not expand it; Claude Code expands `${BLOCKVECTRA_API_KEY}` when it starts the session: ```bash claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \ --header 'x-api-key: ${BLOCKVECTRA_API_KEY}' ``` The same configuration as a project-level `.mcp.json` (also what `claude mcp add --scope project` writes): ```json { "mcpServers": { "blockvectra-docs": { "type": "http", "url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "${BLOCKVECTRA_API_KEY}" } } } } ``` Export `BLOCKVECTRA_API_KEY` in the environment that starts `claude`. Claude Code asks you to approve a project-level `.mcp.json` server the first time you run `claude` in that directory; until then `claude mcp list` shows it as `Pending approval`. For scripts and CI, pass the file with `--mcp-config` and allow the server's tools. The key stays in the environment and the MCP client adds the header itself, so the agent does not need a shell command that expands `$BLOCKVECTRA_API_KEY` (Claude Code's permission check rejected such commands in non-interactive mode with `Contains simple_expansion`): ```bash claude -p "Use rpc_call to run eth_blockNumber on base_mainnet" \ --mcp-config ./mcp.json --allowedTools "mcp__blockvectra-docs__*" ``` With the key set, the `rpc_call` result also contains `cu_charged` and `balance_units`; a keyless call returns only the JSON-RPC response. If the variable is not set, the client sends the literal header text and the server answers `invalid_api_key` (error code `-32024`) instead of falling back to the keyless endpoint. Official documentation: [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp). ### Cursor Add the server to Cursor's MCP configuration: ```json { "mcpServers": { "blockvectra": { "url": "https://docs.blockvectra.com/mcp" } } } ``` Cursor also supports one-click installation via deep links using the base64-encoded configuration `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9` (representing `{"url":"https://docs.blockvectra.com/mcp"}`): ```text cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9 ``` When you need authenticated tools (Data API or account management), add the `headers` object with your API key: ```json { "mcpServers": { "blockvectra": { "url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "${env:BLOCKVECTRA_API_KEY}" } } } } ``` The `${env:NAME}` form follows the Cursor documentation, which resolves variables in `url` and `headers`; this form has not been run against Cursor here. Put the file in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). Official documentation: [Cursor MCP documentation](https://cursor.com/docs/context/mcp) and [Cursor install links](https://cursor.com/docs/context/mcp/install-links). ### VS Code In VS Code, configure the server in `.vscode/mcp.json` under the top-level `servers` key with `type: "http"`: ```json { "servers": { "blockvectra": { "type": "http", "url": "https://docs.blockvectra.com/mcp" } } } ``` When you need authenticated tools, add the `headers` object: ```json { "servers": { "blockvectra": { "type": "http", "url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` When storing sensitive credentials, VS Code supports referencing input variables or environment files instead of hardcoding keys. You can also add servers using the Command Palette action `MCP: Add Server`. Official documentation: [VS Code MCP servers documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) and [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ### Codex Add the server using the OpenAI Codex CLI: ```bash codex mcp add blockvectra --url https://docs.blockvectra.com/mcp ``` In `config.toml`, configure the server URL: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" ``` When you need authenticated tools, configure request headers in `config.toml`: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" http_headers = { "x-api-key" = "YOUR_API_KEY" } ``` Alternatively, map the header from an environment variable: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" } ``` Official documentation: [OpenAI Codex CLI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Gemini CLI In the Gemini CLI configuration, add the server under `mcpServers` using `httpUrl` for Streamable HTTP: ```json { "mcpServers": { "blockvectra": { "httpUrl": "https://docs.blockvectra.com/mcp" } } } ``` When you need authenticated tools, add the `headers` object with your API key: ```json { "mcpServers": { "blockvectra": { "httpUrl": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Official documentation: [Gemini CLI MCP server documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md). ### OpenAI Responses API When calling the OpenAI Responses API, pass the MCP server in the `tools` array with `type: "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": "", "tools": [{ "type": "mcp", "server_label": "blockvectra", "server_url": "https://docs.blockvectra.com/mcp", "require_approval": "never" }], "input": "..." }' ``` When you need authenticated tools, include the `headers` field in the tool definition: ```json { "type": "mcp", "server_label": "blockvectra", "server_url": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" }, "require_approval": "never" } ``` Official documentation: [OpenAI MCP tools guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) and [OpenAI Responses API reference](https://developers.openai.com/api/reference/resources/responses/methods/create). ### Windsurf In Windsurf, configure the server under `mcpServers` using the `serverUrl` field: ```json { "mcpServers": { "blockvectra": { "serverUrl": "https://docs.blockvectra.com/mcp" } } } ``` When you need authenticated tools, add the `headers` object with your API key: ```json { "mcpServers": { "blockvectra": { "serverUrl": "https://docs.blockvectra.com/mcp", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Windsurf also supports referencing environment variables, such as `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`. Official documentation: [Windsurf MCP documentation](https://docs.devin.ai/desktop/cascade/mcp). ### Claude Desktop and claude.ai Custom connectors are configured through the user interface: * **claude.ai**: Navigate to **Customize** > **Connectors**, click **+ Add**, select **Add custom connector**, and enter the URL: ```text https://docs.blockvectra.com/mcp ``` * **Claude Desktop**: Open the account settings menu and configure custom connectors through the connectors interface. Connecting to the URL allows Claude to search guides, read Markdown documentation, inspect supported chains, check network status, and calculate pricing estimates without credentials. Official documentation: [Claude custom connectors guide](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). ### Check the connection and troubleshoot In Claude Code, `claude mcp list` shows each server's status. For a count of the tools that were actually registered, run once with the stream output and read the `init` event, or read the debug log: ```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 ``` A working connection shows `"status": "connected"` and `mcp__blockvectra-docs__*` tools (such as `list_chains` and `rpc_call`) in the `init` event. In the debug log, look for lines about `blockvectra-docs` such as `Successfully connected` and `Failed to fetch tools`. If the server is `connected` but no tools appear, read the reason the debug log (`--debug mcp`) reports after `Failed to fetch tools`. To check that the server itself is healthy, use the curl calls below. ### Call the MCP endpoint without a client The endpoint is JSON-RPC 2.0 over HTTP POST, so any HTTP client can call it: ```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":[]}}}' ``` The first call returns the tool list; the second returns the JSON-RPC response in `result.structuredContent`. Chain identifiers are slugs such as `base_mainnet`; get them from `list_chains`. Keyed tools need the `x-api-key` header; this call reads your account with the key from an environment variable: ```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":{}}}' ``` It returns `key_id`, `plan`, `balance_units`, `balance_cu` and the key's rate limits in `result.structuredContent`. If your agent runs commands through a permission-gated shell, that variable expansion may be blocked; configure the header in the MCP client instead. ## FAQ ### Does the BlockVectra MCP server need an API key? No. Connecting needs no key, and 10 of the 15 tools never need one. `rpc_call` and `send_raw_transaction` run without a key only for methods in the chain's `public.methods` (read it with `list_chains`). `data_api_get`, `get_account` and `get_deposit_address` need the `x-api-key` header. ### Can the MCP server create or revoke API keys? No. No tool creates, lists or revokes API keys. `how_to_get_api_key` only returns the steps; an agent creates a key over HTTP by following [programmatic sign-up](https://docs.blockvectra.com/en/guides/programmatic-signup/), and people create one in the console. Keys never go through tool arguments. ### Can an agent send transactions through the MCP server? It can broadcast, not sign. `rpc_call` rejects write methods such as `eth_sendRawTransaction`, `eth_sendTransaction`, `eth_sign` and `personal_*`. `send_raw_transaction` broadcasts a transaction you already signed locally with `eth_sendRawTransaction`; the server never holds or sees a private key. ### What happens when a call fails? Tool errors return `isError: true` with a structured reason. Use `explain_error` or the [error codes reference](https://docs.blockvectra.com/en/errors/) to see whether a failure is billed and whether to retry. ## Related * [Connect AI agents](https://docs.blockvectra.com/en/guides/ai-agents/): machine-readable files, public JSON endpoints and the chain selection workflow. * [Programmatic sign-up](https://docs.blockvectra.com/en/guides/programmatic-signup/): create an API key with a wallet signature, without a browser. * [Agent framework recipes](https://docs.blockvectra.com/en/guides/agent-frameworks/): ElizaOS, viem, wagmi and Coinbase AgentKit. * [Error codes](https://docs.blockvectra.com/en/errors/): every error with billing and retry rules.