Blockchain RPC and docs MCP for AI Agents

Start with the keyless docs MCP endpoint to discover blockchain RPC methods, Data API datasets, prices and documentation. AI Agents are first-class users: developers and AI Agents use the same APIs, rules, limits and prices.

Connecting from MCP clients

For Claude Code, add the docs MCP server:

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

In your client, ask for these two keyless tool calls in order: discover the chain, then read the quickstart. Neither step needs an account, wallet or API key.

Call list_chains with chain=robinhood_mainnet.
Then call read_doc with path=quickstart and lang=en.

Success means list_chains returns robinhood_mainnet and read_doc returns the quickstart body; registering the tools or seeing them listed does not confirm a successful call.

If installation or connection fails, see Install in your client for configuration, headers and troubleshooting. For a known chain, pass its exact name as chain to list_chains; otherwise use list_chains to discover it. For other tasks, use search_docs, then pass a matching page's path to read_doc.

Continue with the account setup below only for RPC, Data API or account tasks that require authentication.

1. Discover: use docs MCP, llms.txt, OpenAPI and public JSON to choose a chain and method. Keyless RPC calls are limited to the chain's public.methods.
2. Open an account over HTTP: follow programmatic sign-up to sign in with a wallet signature and create an API key. MCP's how_to_get_api_key returns instructions for this separate HTTP flow.
3. Call data APIs: keep the key in BLOCKVECTRA_API_KEY and use it for authenticated RPC or Data API requests. For keyed MCP tools, configure the client's x-api-key header; each tool's allowed operations are listed below.

1. Machine-readable context and specifications

BlockVectra publishes files aimed at LLM agents and developer tools:

llms.txt indexes

Following the llmstxt.org convention, these files give agents a structured summary of the site and its endpoints:

• Main site index: Main site llms.txt — overview of the main site, supported chains, pricing, and public APIs.
• Documentation index: Documentation llms.txt — catalog of every documentation page with its title and description.

Full documentation file (llms-full.txt)

• Complete documentation: llms-full.txt — the full text of every English documentation page in one plain-text Markdown file, suitable for loading into an agent's system prompt or ingesting into a Retrieval-Augmented Generation (RAG) pipeline.

Downloadable OpenAPI 3.1 specifications

The documentation site serves OpenAPI 3.1 YAML files that can be imported directly into agent frameworks, tool generators, or API clients:

• JSON-RPC API specification: /openapi/json-rpc.yaml — supported methods, per-chain method policy, error responses, and Compute Unit metering.
• Data API specification: /openapi/data.yaml — REST endpoint definitions for indexed blocks, transactions, transfers, balances, holders, and related datasets.
• Push API specification: /openapi/push.yaml — HTTP subscription management, watched wallet addresses, webhook events, signatures and replay.

For wallet address activity, follow the Blockchain Webhook API guide. For ERC-20 USDT / USDC payment notifications, use the payment receiver example. Developers and AI agents create and manage subscriptions through the HTTP Push API with x-api-key; the docs MCP provides discovery and reading of these guides.

For path versioning, backward compatibility rules, and recommendations for agents and SDK authors, see API versioning and compatibility. For ready-to-use recipes across popular frameworks (ElizaOS, viem, wagmi, Coinbase AgentKit), see Agent framework recipes.

Model Context Protocol (MCP) server

BlockVectra exposes a stateless MCP server over Streamable HTTP at the MCP endpoint; connecting needs no key. It offers 15 tools: documentation, chains, status and pricing tools work without a key, and keyed tools read x-api-key from the client's headers. Keys never go through tool arguments.

The tool list, key requirements, FAQ and per-client install steps (Claude Code, Cursor, VS Code, Codex, Gemini CLI, OpenAI Responses API, Windsurf) are on the BlockVectra MCP server page.

One API integration

If your agent already works through One, you can pick BlockVectra actions from its public API catalog, such as daily DEX token prices. For a direct MCP connection, use the client setup above instead. Authentication uses your own BlockVectra key, sent as x-api-key; see programmatic sign-up to get one. Keep the key in One's private connection settings, never in an agent prompt or action parameter. For a price action, give the chain, token, quote and UTC date explicitly. Treat the response's freshness and coverage as the source of truth: a missing or empty daily price is not a price of zero. Request parameters are in the Data API reference.

2. Public JSON endpoints (no key required)

An agent can inspect available chains, live status, and plan parameters before sending any metered request. None of these endpoints needs an API key:

• GET /v1/status and GET /v1/chains are unauthenticated and unbilled.
• GET /v1/plans is public and unauthenticated.

All three send Access-Control-Allow-Origin: *.

Service status (GET /v1/status)

Returns the service's readiness and the synchronization status of each public chain:

curl -s "https://api.blockvectra.com/v1/status"

Response fields:

• checked_at: when the snapshot was generated (RFC 3339 / ISO 8601 UTC).
• gateway.status: service running status. ok means the service is ready; degraded means paid requests are rejected until it recovers. This value is independent of any chain's node status.
• chains[]: the chains served to the public:
  • chain: chain slug (e.g. robinhood_mainnet).
  • name: human-readable display name.
  • chain_id: EIP-155 chain ID (decimal integer).
  • jsonrpc: whether JSON-RPC is served.
  • data: whether the Data API is served.
  • data_features: Data API capabilities available for this chain (an empty array when data is false).
  • data_status: Data API running status (ok, syncing, or unavailable; present only when data is true).
  • status: chain node status (ok or unavailable).
  • head: latest block information — block (latest block height), time (block timestamp), and lag_seconds (how far the block time lags the current time) — or null when unknown.

Example response:

{
  "checked_at": "2026-09-28T12:00:00Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "status": "ok",
      "head": {
        "block": 73017329,
        "time": "2026-09-28T11:59:58Z",
        "lag_seconds": 2
      }
    }
  ]
}

Chain parameters (GET /v1/chains)

Returns each public chain's static parameters and method policy:

curl -s "https://api.blockvectra.com/v1/chains"

Response fields:

• chains[]: public chains and their static parameters:
  • chain: chain slug.
  • name: human-readable display name.
  • chain_id: EIP-155 chain ID.
  • jsonrpc: whether JSON-RPC is served.
  • data: whether the Data API is served.
  • ws: whether WebSocket connections are supported.
  • subscriptions: supported WebSocket subscription types (e.g. newHeads, logs).
  • methods: method policy:
    • allow: allowed method names (e.g. eth_call, debug_traceTransaction).
    • deny: denied methods or prefix wildcard patterns (e.g. eth_newFilter). Denied methods take precedence over allowed ones.
  • max_logs_block_range: maximum block span allowed in a single eth_getLogs request.
  • state_window_blocks: historical state window in blocks; null when the full history is available.
  • info: per-chain public extension data (reserved; currently an empty object {}).
  • public: unauthenticated public endpoint configuration. Only chains offering public JSON-RPC include this object; other chains omit the field:
    • url: base URL for public requests.
    • methods: methods permitted on the public endpoint.
    • rate_limit: rate limits (per_ip_rps, burst, batch_max).
    • history_blocks: block history accessible on the public endpoint.
    • send_raw_rate_limit: rate limits for broadcasting transactions via eth_sendRawTransaction.

Example response:

{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "ws": true,
      "subscriptions": [
        "newHeads",
        "logs"
      ],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "debug_traceTransaction"
        ],
        "deny": [
          "eth_newFilter",
          "eth_newBlockFilter",
          "eth_newPendingTransactionFilter",
          "eth_getFilterLogs",
          "eth_getFilterChanges",
          "eth_uninstallFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 900,
      "info": {},
      "public": {
        "url": "https://api.blockvectra.com/v1/robinhood_mainnet/public",
        "methods": [
          "eth_chainId",
          "net_version",
          "eth_blockNumber",
          "eth_call"
        ],
        "rate_limit": {
          "per_ip_rps": 3,
          "burst": 20,
          "batch_max": 10
        },
        "history_blocks": 128,
        "send_raw_rate_limit": {
          "per_ip_rps": 1,
          "burst": 3
        }
      }
    }
  ]
}

Plans and method weights (GET /v1/plans)

Plan parameters are served at GET https://console-api.blockvectra.com/v1/plans. An agent can query this endpoint at runtime to read the active free-plan limits and the Compute Unit (CU) weight of each method:

• free: Free Plan parameters — signup_units (sign-up grant, in units), monthly_units (cycle refill watermark, in units), window_days (usage cycle length in days), and max_calls_per_sec (free-plan per-second call cap).
• pricing: paid-plan parameters — units_per_usd (units per 1 USD), cu_per_unit (CU per unit), and min_topup_usd (minimum top-up in USD).
• method_weights: per-call CU weights, each { "method": string, "cu_weight": number }. method specifies the JSON-RPC method name or pattern, default weights for unlisted methods, or a Data API operation such as data.<op>. Weights are per method and are not split by chain.

3. Authentication and key security

Agents that issue RPC calls must follow these rules:

• Authentication: pass the API key in one of three ways. In the path: POST /v1/{chain}/{api_key} — the path form uses only the key in the path and ignores both headers. In the x-api-key header: POST /v1/{chain} with x-api-key: $BLOCKVECTRA_API_KEY. In the Authorization header: POST /v1/{chain} with Authorization: Bearer $BLOCKVECTRA_API_KEY. When both headers are present, a non-empty x-api-key wins; Bearer is used only when x-api-key is missing or empty. The same key works on every supported chain, and on the Data API (which accepts the key only in the x-api-key header).
• Key security: keep API keys in server-side environment variables (for example BLOCKVECTRA_API_KEY) or a secrets manager. Never embed a key in browser code or any client-side bundle. Endpoints do return Access-Control-Allow-Origin: *, but they are meant to be called by backend services rather than from the browser.
• Metering and upgrades: usage is metered in Compute Units (CU): each method consumes CU according to its weight, and balance, CU buckets, and free-plan rate limits are shared across all chains. After a paid top-up, the free plan's per-second call cap no longer applies; each key still has a CU rate limit and burst capacity. Unused Free Credits stay in your Credits and can still be used. See the Pricing page for details.

Query balance (GET /v1/account)

An agent can check its key's current balance, CU limits, and key parameters directly without consuming Compute Units (CU). For the request format, rate limits, and full response field definitions, see Query balance: GET /v1/account.

4. Chain selection workflow for agents

Before dispatching calls, an agent can follow these steps:

1. Check the chain and its method policy: call GET /v1/chains, confirm that the target chain exists and has jsonrpc: true, and that the method you plan to call is allowed by methods.allow and not denied by methods.deny (deny wins).
2. Check live status: call GET /v1/status and confirm that gateway.status is ok and that the target chain's status is ok; use head.lag_seconds to decide whether the chain's data is fresh enough for your use case. When a chain's node is not synced, every method except eth_chainId returns JSON-RPC error -32010 (HTTP 200, not billed), so the agent can wait and retry or pick another chain.
3. Send the request: POST /v1/{chain} with the x-api-key header and a standard JSON-RPC body.

5. Minimal working example

The example below reads /v1/chains to pick a chain that allows eth_blockNumber, checks /v1/status, and then calls eth_blockNumber once.

The examples exit with an error on non-2xx HTTP, invalid JSON, or JSON-RPC errors. They print success only for version 2.0, integer id: 1, no error key, and a canonical hex quantity in result (including 0x0). The cURL example requires python3.

set -eu
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# Reject every non-2xx status, including redirects.
request() {
  response=$(curl -fsS -w '\n%{http_code}' "$@") || return "$?"
  case "${response##*$'\n'}" in
    2[0-9][0-9]) printf '%s' "${response%$'\n'*}" ;;
    *) return 1 ;;
  esac
}

chains=$(request "https://api.blockvectra.com/v1/chains")
status=$(request "https://api.blockvectra.com/v1/status")

# Select an allowed chain and check readiness before the RPC call.
chain=$(CHAINS="$chains" STATUS="$status" python3 - <<'PYTHON'
import json
import os


def matches(pattern, method):
    return pattern == method or (pattern.endswith("*") and method.startswith(pattern[:-1]))


selected = next((
    c for c in json.loads(os.environ["CHAINS"])["chains"]
    if c["jsonrpc"]
    and not any(matches(p, "eth_blockNumber") for p in c["methods"]["deny"])
    and any(matches(p, "eth_blockNumber") for p in c["methods"]["allow"])
), None)
if selected is None:
    raise RuntimeError("No chain found that allows eth_blockNumber")

status = json.loads(os.environ["STATUS"])
chain_status = next((c for c in status["chains"] if c["chain"] == selected["chain"]), None)
if status["gateway"]["status"] != "ok" or chain_status is None or chain_status["status"] != "ok":
    raise RuntimeError("Selected chain is currently unavailable")
print(selected["chain"])
PYTHON
)

default_endpoint="https://api.blockvectra.com/v1/robinhood_mainnet"
rpc_response=$(request "${default_endpoint%/*}/$chain" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H "x-bv-meter: 1" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}')

RPC_RESPONSE="$rpc_response" python3 - <<'PYTHON'
import json
import os
import re

rpc_response = json.loads(os.environ["RPC_RESPONSE"])
if (
    not isinstance(rpc_response, dict)
    or rpc_response.get("jsonrpc") != "2.0"
    or type(rpc_response.get("id")) is not int
    or rpc_response["id"] != 1
    or "error" in rpc_response
    or "result" not in rpc_response
    or not isinstance(rpc_response["result"], str)
    or re.fullmatch(r"0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)", rpc_response["result"]) is None
):
    raise RuntimeError("Invalid eth_blockNumber response")

print("Response:", rpc_response)
PYTHON

A successful call returns a standard JSON-RPC response object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}

To inspect per-request CU charges and remaining balance units in response headers, include x-bv-meter: 1. For header behavior and error cases, see Charge and balance response headers.

Next steps

• Browse the datasets directory to see every dataset BlockVectra indexes.
• See the free plan and pricing to check what your account includes.
• Follow the programmatic sign-up guide to sign up and create an API key with a wallet signature, or log in to the console to create a key.