Servidor MCP da BlockVectra: RPC de blockchain e ferramentas de documentação para agentes de IA

O servidor MCP da BlockVectra em https://docs.blockvectra.com/mcp oferece a desenvolvedores e agentes de IA 15 ferramentas para chamadas RPC de blockchain, status das redes, preços e documentação. Ele não precisa de API key para conectar: 10 ferramentas nunca precisam de uma; as demais usam o x-api-key dos cabeçalhos do seu cliente. Instale em uma linha: claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp

O endpoint é o endpoint MCP (HTTP POST recebendo JSON-RPC 2.0; GET retorna 405), servido via MCP Streamable HTTP e sem estado. Para os arquivos HTTP, o JSON público e o fluxo de cadastro que os acompanha, consulte Conectar agentes de IA.

Ferramentas

Esta tabela é gerada a partir do registro de ferramentas do servidor, portanto lista todas as ferramentas que tools/list retorna. Cada ferramenta recebe os argumentos e retorna os campos descritos em seu próprio schema de tools/list.

Segurança da API key

As ferramentas autenticadas precisam de uma API key para executar requisições à Data API, operações de conta ou métodos RPC fora dos métodos públicos de uma rede.

• Leitura estrita a partir dos cabeçalhos: A API key é lida exclusivamente dos cabeçalhos de requisição HTTP do cliente MCP (x-api-key: rgw_... ou Authorization: Bearer rgw_...).
• Nunca insira chaves no chat: Nunca passe API keys ou chaves privadas em argumentos de ferramentas nem as cole no chat. Argumentos de ferramentas e histórico de chat entram em logs e contextos de conversas; passar chaves em argumentos será rejeitado.

Se forem chamadas sem um cabeçalho de API key, as ferramentas autenticadas retornam isError: true e direcionam o agente para how_to_get_api_key e o guia de cadastro programático.

Instalar no seu cliente

Você pode se conectar ao servidor MCP de documentação da BlockVectra em https://docs.blockvectra.com/mcp nos ambientes de desenvolvimento e frameworks mais comuns.

Comece sem uma API key. Conecte-se ao endpoint MCP, chame list_chains e, em seguida, leia o quickstart com read_doc. Adicione uma API key nos cabeçalhos HTTP do seu cliente quando precisar da Data API ou de ferramentas de conta. O acesso RPC sem chave segue a política de métodos públicos de cada rede.

O cabeçalho x-api-key é opcional. Sem uma API key, os clientes podem usar todas as ferramentas de documentação somente leitura (read_doc, search_docs, list_docs), descoberta de redes (list_chains), status em tempo real (get_status), estimativa de preços (get_pricing, estimate_usage), explicações de erros (explain_error) e métodos permitidos em endpoints públicos. Ao usar ferramentas autenticadas (rpc_call em métodos restritos, send_raw_transaction, data_api_get, get_account e get_deposit_address), configure o cabeçalho x-api-key com sua API key.

Claude Code

Conecte-se ao servidor MCP usando a CLI:

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

Para incluir uma API key opcional para ferramentas autenticadas, passe a opção --header (ou -H) e referencie uma variável de ambiente em vez de colar a chave. Use aspas simples para que o seu shell não a expanda; o Claude Code expande ${BLOCKVECTRA_API_KEY} quando inicia a sessão:

claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header 'x-api-key: ${BLOCKVECTRA_API_KEY}'

A mesma configuração como um .mcp.json no nível do projeto (também o que claude mcp add --scope project grava):

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

Exporte BLOCKVECTRA_API_KEY no ambiente que inicia o claude. O Claude Code pede que você aprove um servidor do .mcp.json no nível do projeto na primeira vez que executa claude nesse diretório; até lá, claude mcp list o mostra como Pending approval.

Para scripts e CI, passe o arquivo com --mcp-config e permita as ferramentas do servidor. A chave permanece no ambiente e o cliente MCP adiciona o cabeçalho por conta própria, de modo que o agente não precisa de um comando de shell que expanda $BLOCKVECTRA_API_KEY (a verificação de permissões do Claude Code rejeitava esses comandos no modo não interativo com Contains simple_expansion):

claude -p "Use rpc_call to run eth_blockNumber on base_mainnet" \
  --mcp-config ./mcp.json --allowedTools "mcp__blockvectra-docs__*"

Com a chave definida, o resultado de rpc_call também contém cu_charged e balance_units; uma chamada sem chave retorna apenas a resposta JSON-RPC. Se a variável não estiver definida, o cliente envia o texto literal do cabeçalho e o servidor responde invalid_api_key (código de erro -32024) em vez de recorrer ao endpoint sem chave.

Documentação oficial: documentação de MCP do Claude Code.

Cursor

Adicione o servidor à configuração de MCP do Cursor:

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

O Cursor também suporta instalação em um clique por meio de deep links usando a configuração codificada em base64 eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9 (representando {"url":"https://docs.blockvectra.com/mcp"}):

cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9

Quando precisar de ferramentas autenticadas (Data API ou gerenciamento de conta), adicione o objeto headers com sua API key:

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

A forma ${env:NAME} segue a documentação do Cursor, que resolve variáveis em url e headers; esta forma não foi executada no Cursor aqui. Coloque o arquivo em .cursor/mcp.json (projeto) ou ~/.cursor/mcp.json (global).

Documentação oficial: documentação de MCP do Cursor e links de instalação do Cursor.

VS Code

No VS Code, configure o servidor em .vscode/mcp.json sob a chave de nível superior servers com type: "http":

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

Quando precisar de ferramentas autenticadas, adicione o objeto headers:

{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Ao armazenar credenciais confidenciais, o VS Code permite referenciar variáveis de entrada ou arquivos de ambiente em vez de fixar as chaves no código. Você também pode adicionar servidores usando a ação MCP: Add Server da Paleta de Comandos.

Documentação oficial: documentação de servidores MCP do VS Code e referência de configuração MCP do VS Code.

Codex

Adicione o servidor usando a CLI do OpenAI Codex:

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

Em config.toml, configure a URL do servidor:

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

Quando precisar de ferramentas autenticadas, configure os cabeçalhos de requisição em config.toml:

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }

Alternativamente, mapeie o cabeçalho a partir de uma variável de ambiente:

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }

Documentação oficial: documentação de MCP da CLI do OpenAI Codex.

Gemini CLI

Na configuração da Gemini CLI, adicione o servidor sob mcpServers usando httpUrl para Streamable HTTP:

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

Quando precisar de ferramentas autenticadas, adicione o objeto headers com sua API key:

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

Documentação oficial: documentação de servidor MCP da Gemini CLI.

OpenAI Responses API

Ao chamar a OpenAI Responses API, passe o servidor MCP no array tools com 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": "..."
  }'

Quando precisar de ferramentas autenticadas, inclua o campo headers na definição da ferramenta:

{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}

Documentação oficial: guia de ferramentas MCP da OpenAI e referência da OpenAI Responses API.

Windsurf

No Windsurf, configure o servidor sob mcpServers usando o campo serverUrl:

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

Quando precisar de ferramentas autenticadas, adicione o objeto headers com sua API key:

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

O Windsurf também suporta referenciar variáveis de ambiente, como "x-api-key": "${env:BLOCKVECTRA_API_KEY}".

Documentação oficial: documentação de MCP do Windsurf.

Claude Desktop e claude.ai

Os conectores personalizados são configurados pela interface do usuário:

• claude.ai: Navegue até Customize > Connectors, clique em + Add, selecione Add custom connector e insira a URL:

  Copiar texto

  https://docs.blockvectra.com/mcp

• Claude Desktop: Abra o menu de configurações da conta e configure conectores personalizados por meio da interface de conectores.

Conectar-se à URL permite que o Claude pesquise guias, leia a documentação em Markdown, inspecione as redes suportadas, verifique o status da rede e calcule estimativas de preço sem necessidade de credenciais.

Documentação oficial: guia de conectores personalizados do Claude.

Verificar a conexão e solucionar problemas

No Claude Code, claude mcp list mostra o status de cada servidor. Para obter a contagem das ferramentas que foram realmente registradas, execute uma vez com a saída em stream e leia o evento init, ou leia o log de depuração:

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

Uma conexão funcionando mostra "status": "connected" e as ferramentas mcp__blockvectra-docs__* (como list_chains e rpc_call) no evento init. No log de depuração, procure linhas sobre blockvectra-docs como Successfully connected e Failed to fetch tools. Se o servidor estiver connected mas nenhuma ferramenta aparecer, leia o motivo que o log de depuração (--debug mcp) informa depois de Failed to fetch tools. Para verificar se o próprio servidor está saudável, use as chamadas curl abaixo.

Chamar o endpoint MCP sem um cliente

O endpoint é JSON-RPC 2.0 sobre HTTP POST, portanto qualquer cliente HTTP pode chamá-lo:

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":[]}}}'

A primeira chamada retorna a lista de ferramentas; a segunda retorna a resposta JSON-RPC em result.structuredContent. Os identificadores de rede são slugs como base_mainnet; obtenha-os com list_chains. As ferramentas autenticadas precisam do cabeçalho x-api-key; esta chamada lê a sua conta com a chave vinda de uma variável de ambiente:

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

Ela retorna key_id, plan, balance_units, balance_cu e os limites de taxa da chave em result.structuredContent. Se o seu agente executa comandos por meio de um shell com controle de permissões, essa expansão de variável pode ser bloqueada; configure o cabeçalho no cliente MCP.

FAQ

O servidor MCP da BlockVectra precisa de uma API key?

Não. Conectar não exige chave, e 10 das 15 ferramentas nunca precisam de uma. rpc_call e send_raw_transaction funcionam sem chave apenas para os métodos em public.methods da rede (leia com list_chains). data_api_get, get_account e get_deposit_address precisam do cabeçalho x-api-key.

O servidor MCP pode criar ou revogar API keys?

Não. Nenhuma ferramenta cria, lista ou revoga API keys. how_to_get_api_key apenas retorna as etapas; um agente cria uma chave via HTTP seguindo o cadastro programático, e as pessoas criam uma no console. As chaves nunca passam por argumentos de ferramentas.

Um agente pode enviar transações pelo servidor MCP?

Ele pode transmitir, não assinar. rpc_call rejeita métodos de escrita como eth_sendRawTransaction, eth_sendTransaction, eth_sign e personal_*. send_raw_transaction transmite com eth_sendRawTransaction uma transação que você já assinou localmente; o servidor nunca guarda nem vê uma chave privada.

O que acontece quando uma chamada falha?

Os erros de ferramentas retornam isError: true com um motivo estruturado. Use explain_error ou a referência de códigos de erro para ver se uma falha é cobrada e se vale tentar novamente.

Relacionados

• Conectar agentes de IA: arquivos legíveis por máquina, endpoints JSON públicos e o fluxo de seleção de redes.
• Cadastro programático: crie uma API key com uma assinatura de carteira, sem navegador.
• Receitas de frameworks de agentes: ElizaOS, viem, wagmi e Coinbase AgentKit.
• Códigos de erro: todos os erros com regras de cobrança e de nova tentativa.