BlockVectra MCP server: blockchain RPC and docs tools for AI agents

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 (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.

Tools

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.

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:

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:

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):

{
  "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):

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.

Cursor

Add the server to Cursor's MCP configuration:

{
  "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"}):

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:

{
  "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 and Cursor install links.

VS Code

In VS Code, configure the server in .vscode/mcp.json under the top-level servers key with type: "http":

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

When you need authenticated tools, add the headers object:

{
  "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 and VS Code MCP configuration reference.

Codex

Add the server using the OpenAI Codex CLI:

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

In config.toml, configure the server URL:

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

When you need authenticated tools, configure request headers in config.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:

[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.

Gemini CLI

In the Gemini CLI configuration, add the server under mcpServers using httpUrl for Streamable HTTP:

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

When you need authenticated tools, add the headers object with your API key:

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

Official documentation: Gemini CLI MCP server documentation.

OpenAI Responses API

When calling the OpenAI Responses API, pass the MCP server in the tools array with type: "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": "..."
  }'

When you need authenticated tools, include the headers field in the tool definition:

{
  "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 and OpenAI Responses API reference.

Windsurf

In Windsurf, configure the server under mcpServers using the serverUrl field:

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

When you need authenticated tools, add the headers object with your API key:

{
  "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.

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:

  Copy 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.

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:

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:

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:

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, 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 to see whether a failure is billed and whether to retry.

Related

• Connect AI agents: machine-readable files, public JSON endpoints and the chain selection workflow.
• Programmatic sign-up: create an API key with a wallet signature, without a browser.
• Agent framework recipes: ElizaOS, viem, wagmi and Coinbase AgentKit.
• Error codes: every error with billing and retry rules.