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

The BlockVectra Model Context Protocol (MCP) server gives developers and AI agents keyless blockchain RPC, chain status, pricing and docs tools, with one-line install for Claude Code, Cursor, VS Code, Codex, Gemini CLI, Antigravity and more.

The BlockVectra Model Context Protocol (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.

To compare endpoints for your workload, use the RPC provider checklist to check method costs, historical coverage and recovery.

Set up your MCP client

Choose the setup instructions for your client:

Once connected, ask your agent to call read_doc with {"path":"quickstart","lang":"en"}. This documentation lookup needs no BlockVectra API key.

Only need to look things up in the docs? Jump to Docs-only remote HTTP.

SDK examples

Use these standalone examples to connect to /mcp/docs, search the documentation and read a returned page without a model or BlockVectra credentials:

Tasks on Robinhood Chain

Agent Skill

The blockvectra-docs Agent Skill helps your coding agent find the right BlockVectra page for a task and answer with the source attached. With the MCP server configured, it uses search_docs then read_doc; otherwise it reads the Markdown pages over HTTP. Looking up docs needs no BlockVectra account or API key.

The Skill only covers documentation. It does not set up MCP for you or run RPC calls, account creation or transactions, so keep following the install steps on this page for MCP.

Run this in your own project (Node.js 22.20 or later) and pick the agent you use:

npx --yes skills@1.7.4 add blockvectra/agent-quickstart --skill blockvectra-docs

Then ask, for example: "How do I get started on Robinhood Chain? Separate mainnet from testnet and cite the docs." The source is in agent-quickstart.

Tools

ToolWhat it doesAPI keyAccess
read_docRead a documentation page as Markdown.Not neededRead-only
search_docsSearch documentation titles, paths and summaries.Not neededRead-only
list_chainsList supported chains, parameters and method policies (GET /v1/chains).Not neededRead-only
get_statusRead live service and chain status (GET /v1/status).Not neededRead-only
get_pricingRead Compute Unit weights, Free Plan parameters and key defaults (GET /v1/plans).Not neededRead-only
estimate_usageEstimate Compute Units and cost for one or more methods.Not neededRead-only
how_to_get_api_keyReturn the steps for getting an API key and the request authentication shapes.Not neededRead-only
get_method_infoShow a method's chain availability, CU weight and price.Not neededRead-only
explain_errorLook up an error's meaning, billing, retryability and recovery.Not neededRead-only
list_docsList every documentation page with its path and title.Not neededRead-only
rpc_callRun a read-only JSON-RPC method on a supported chain.Optional: keyless only for methods in the chain's public.methodsRead-only
data_api_getSend a GET request to the Data API of a supported chain.Required (x-api-key header)Read-only
get_accountRead account balance, CU and rate limits (GET /v1/account).Required (x-api-key header)Read-only
get_deposit_addressRead the account's deposit address, open networks and tokens.Required (x-api-key header)Read-only
send_raw_transactionBroadcast an already signed raw transaction (eth_sendRawTransaction).Optional: keyless only for methods in the chain's public.methodsBroadcasts 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. Configure the key only in your MCP client's HTTP headers: x-api-key or Authorization: Bearer …. Keep private keys local; do not send credentials in tool arguments, URLs or chat.

Argument credential rules

These rules apply to every tool, including objects nested inside arrays and extra properties that an input schema leaves open:

  • For field-name comparison, convert only ASCII A-Z to a-z, then remove ASCII _ and -. Do not trim whitespace, split dots or fold Unicode characters.
  • At every depth, the normalized names apikey, xapikey, authorization, privatekey and secretkey are reserved. Examples include api_key, apiKey, API_KEY, x-api-key, xApiKey, Authorization, privateKey and secret_key. The normalized name key is also reserved at the argument root; a nested generic key, publicKey or key_id is not reserved by this rule.
  • A reserved field is rejected whenever it is present, including a value of null, an empty string, false, zero, an array or an object.
  • String values at every depth are checked for the case-sensitive API-key marker (?:^|[^A-Za-z0-9_-])rgw_[A-Za-z0-9_-]+(?=$|[^A-Za-z0-9_-]) and the uppercase PEM marker -----BEGIN (?:RSA |EC |OPENSSH |ENCRYPTED )?PRIVATE KEY-----. For example, the synthetic marker rgw_example is rejected; this does not assert that it is a valid API key.
  • Opaque values are not decoded. JSON embedded in a string is not parsed as an object, but its literal characters are still checked for those markers. Bare hashes, public keys and signed raw-transaction hex are not classified as credentials solely by length; the literal invalid-secret-placeholder alone is not a recognized marker. Do not send real credentials in any encoding: an accepted opaque value is not proof that it is safe to disclose.

For a known tool, omitted arguments retain the tool's existing behavior. Present arguments must be an object: null, arrays and scalar roots are rejected. The credential rules run before the tool's published input-schema checks and before header authentication or execution. Other properties remain subject to that input schema; this policy does not close objects whose schema allows extra properties. Unknown tool names remain JSON-RPC protocol errors.

Input rejection responses

A local input rejection returns HTTP 200, Cache-Control: no-store and result.isError: true. result.structuredContent is a required object with exactly error, reason and message; a text content block contains JSON that decodes to the same object. The error is invalid_tool_arguments, and the fixed message does not echo supplied fields, paths or values.

reasonAction before retrying
invalid_rootSend an object, or omit arguments if the tool supports omission.
schema_typeMatch the published input-schema types.
schema_enumUse a value allowed by the published input schema.
undeclared_propertyRemove properties rejected by the input schema.
credential_fieldRemove reserved fields; configure API keys in the client HTTP headers and keep private keys local.
credential_valueRemove recognized credential material; configure API keys in headers and keep private keys local.

For example, search_docs arguments {"query":"RPC","extra":[{"privateKey":null}]} return this object in result.structuredContent and matching JSON text:

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

Clients that previously matched free-text input errors should read structuredContent.error and structuredContent.reason instead. If a keyed tool is called without an API-key header, follow its how_to_get_api_key hint or the programmatic sign-up guide.

Executor request rejections

After the input checks above and any required header authentication, the following tool-specific rejections return HTTP 200, Cache-Control: no-store and result.isError: true. result.structuredContent is a required, non-null object with exactly error, reason and message. error is executor_request_rejected; reason is limited to the values for that tool below; message is the existing explanation for the rejected request. There is exactly one text content block containing JSON that decodes to the same object.

Toolreason and rejection condition
search_docsquery_required: query is missing or empty after trimming.
estimate_usagemethod_required: a selected estimate line has no non-empty trimmed method; calls_per_day_invalid: that line's daily calls are missing or not a finite, non-negative integer. These apply to single-method estimates and individual lines entries.
get_method_infomethod_required: method is missing or empty after trimming.
rpc_callchain_required or method_required: the respective value is missing or empty after trimming; unknown_chain: the existing chain-catalog lookup completes but finds no matching chain slug.
data_api_getchain_invalid: the trimmed chain is empty or contains characters outside [A-Za-z0-9_-]; path_invalid: path is missing or empty, starts with /, contains .. or //, or contains ?, # or %.
send_raw_transactionchain_required or raw_tx_required: the respective value is missing or empty after trimming; unknown_chain: the existing chain-catalog lookup completes but finds no matching chain slug.

For example, get_method_info with {} returns this object in structuredContent and equal JSON text:

{
  "error": "executor_request_rejected",
  "reason": "method_required",
  "message": "Missing or invalid 'method' parameter"
}

These rejections are separate from invalid_tool_arguments; input-schema type, enum and credential checks keep their precedence. data_api_get still requires an API-key header before its tool-specific checks. Failed catalog retrieval, other path-character checks, estimate container errors and other existing errors keep their existing payloads. Each tool's published output schema retains its original success, error and truncated-result contract alongside the exact new rejection branch. An object marked executor_request_rejected must satisfy that tool's complete rejection schema; the original branch cannot accept a malformed object with this discriminator.

Moving off Smithery proxy connections

Smithery has announced that on 2026-10-31 it stops connection management and the run.tools / server.smithery.ai proxy connections; its public, non-proxy directory remains (announcement). If your BlockVectra configuration still uses one of those proxy domains, switch it to https://docs.blockvectra.com/mcp and use the client configuration below. Connecting and reading documentation needs no API key; keyed tools keep their existing header authentication. To check the connection, call read_doc with quickstart and lang set to en.

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, data_api_get, get_account, and get_deposit_address), configure the x-api-key header with your API key.

Docs-only remote HTTP

For documentation lookup, connect to https://docs.blockvectra.com/mcp/docs. This endpoint exposes only search_docs and read_doc; it needs no BlockVectra account, API key, or local Node.js installation. Adding an API key does not enable other tools.

For Claude Code, run this one line:

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

The command and the project .mcp.json below are alternatives; use one. This command does not replace or migrate an existing server of the same name, so if you already configured the full /mcp server, keep whichever one you want using your client's usual server management. To configure it in a project file instead, add this to .mcp.json:

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

In other clients, use their remote HTTP configuration format below with the same URL. For a first read, ask your agent to call search_docs with your task, then call read_doc with the path from a result and the same lang. To read the quickstart directly, call read_doc with {"path":"quickstart","lang":"en"}. Use the full /mcp endpoint for chain discovery, RPC, Data API, pricing, or account tools.

Docs-only local stdio (Node.js 22+)

If your client only needs to look things up in the documentation, you can run a docs-only local server. It exposes just two tools, search_docs and read_doc, reads public documentation over HTTP, and needs no BlockVectra account or API key. An inherited BLOCKVECTRA_API_KEY is not forwarded. RPC, Data API and account tools are not part of this mode.

Install the GitHub 0.1.1 package below; the npm @blockvectra/mcp@0.1.0 package does not include this command. Downloading the package and its dependencies, and later documentation lookups, need a network connection. For a downloaded package, check its SHA-256 against the release's SHA256SUMS before installing it locally.

{
  "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"
      ]
    }
  }
}

After the client restarts, check that it lists only search_docs and read_doc, then call read_doc with path set to guides/robinhood-chain and lang set to en to read the guide on Robinhood Chain. The restriction applies to this MCP connection only. To use chain discovery, RPC or keyed tools, pick the full bridge below instead; configure one of the two, not both, so you don't end up with duplicate servers.

Local stdio (Node.js 22+)

Connect to the hosted BlockVectra MCP service using the @blockvectra/mcp local stdio bridge (requires Node.js 22+ and an active network connection).

Add the server to your client's MCP configuration:

{
  "mcpServers": {
    "blockvectra": {
      "command": "npx",
      "args": ["-y", "@blockvectra/mcp@0.1.0"]
    }
  }
}

Initialization, documentation tools (read_doc, search_docs, list_docs), and supported public methods do not require an API key.

When using keyed tools (such as Data API requests or account operations), set BLOCKVECTRA_API_KEY in the environment that launches the bridge process. If your client supports a per-server env field, you can use that field to inject the local secret value. The bridge only converts this environment variable to the x-api-key header and never places keys into CLI arguments, prompts, or tool arguments. Note that GUI clients might not automatically inherit shell environment variables. Calling keyed tools without an API key directs the agent to how_to_get_api_key and the programmatic sign-up guide.

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

Connect with the Gemini CLI extension:

gemini extensions install https://github.com/blockvectra/mcp --ref main

Restart Gemini CLI, then run /mcp to confirm the blockvectra-docs server and its tools are loaded. Discovery works without an API key: ask for list_chains, or read_doc with path=quickstart and lang=en. For keyed tools, see optional authentication.

The extension and the manual configuration below are alternatives. Use one, not both, so you don't register duplicate servers.

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.

Antigravity

Install the BlockVectra documentation plugin in Antigravity:

agy plugin install https://github.com/blockvectra/mcp

The plugin connects directly to https://docs.blockvectra.com/mcp over remote HTTP; there is no local npm bridge to run. Restart Antigravity, then use /plugin in a signed-in session to check that it is enabled and /mcp to see its tools. To verify the connection, ask Antigravity to call list_chains, then read_doc with path=quickstart and lang=en.

Connecting, documentation, chain discovery, pricing and status tools need no API key. RPC calls follow each chain's public method policy. Data API and account tools need your own key, configured only in private HTTP headers; keep it out of command arguments, tool arguments and chat. See the BlockVectra MCP repository for plugin and authentication details, and the official Antigravity plugins and MCP documentation.

goose

goose can run MCP servers and packaged recipes. After installing goose and configuring a model provider, fetch the pinned recipe, validate it, and run it:

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

The recipe connects to https://docs.blockvectra.com/mcp over Streamable HTTP and uses only search_docs and read_doc. Its fixed task searches for the public RPC setup on Robinhood Chain mainnet, then reads guides/robinhood-chain with lang=en. The result should describe the mainnet configuration and keep the testnet faucet separate. The recipe queries documentation only; it does not execute RPC calls, send transactions or create accounts.

Connecting and these two documentation tools need no BlockVectra account or API key. Model calls go through the provider you configured for goose and are billed under that provider's rules.

If the run fails, check the goose and provider configuration and the goose recipe validate output first.

Pinned recipe source: recipes/goose-docs.json. Official documentation: goose recipes.

Hermes Agent

Hermes Agent connects to remote HTTP MCP servers natively. Add BlockVectra under mcp_servers in ~/.hermes/config.yaml, merging it into the existing mapping so other servers stay configured:

mcp_servers:
  blockvectra:
    url: https://docs.blockvectra.com/mcp

Save the file and start a new Hermes session so the server loads. Connecting and the documentation tools need no API key; for keyed tools, pass x-api-key in the request headers following this page's HTTP header authentication rules.

For a known chain, pass chain to list_chains, such as robinhood_mainnet, rather than enumerating every chain. For a specific task, call search_docs and then read the matching page.

Official documentation: Hermes Agent MCP 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:
    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.

Find and read a guide without an API key

This example runs two tools/call requests in sequence: search_docs finds a guide, then read_doc reads it. Neither call sends x-api-key. It needs Python 3 and nothing else (standard library only). Save it as read_guide.py and run python3 read_guide.py.

import json
import os
import sys
import urllib.request

URL = "https://docs.blockvectra.com/mcp"
LANG = "en"
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": "faucet on 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("No match: try other words, or browse with list_docs.")
path = results[0]["path"]
print("Reading:", path, file=sys.stderr)

doc = call(2, "read_doc", {"path": path, "lang": LANG})
print(doc["content"][0]["text"])

The script passes the path from the first search result to read_doc unchanged, and reuses the same lang. path is relative, such as guides/example: do not add a domain, a leading / or a query string. The guide text comes back as Markdown in result.content[0].text; read_doc returns no structuredContent. The script exits without a second request when the HTTP call or JSON-RPC request fails, when a tool returns isError: true, or when results is empty (an empty result is not an error, but there is nothing to read; change the query or browse with list_docs). It does not retry. It only reads the guide: it does not run any command the guide contains.

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?

Check result.isError before using a tool result, and read the returned error message. Use explain_error or the error codes reference to see whether a failure is billed and whether to retry.

Last updated:

On this page