# Servidor MCP da BlockVectra: RPC de blockchain e ferramentas de documentação para agentes de IA > Source: https://docs.blockvectra.com/pt-br/guides/mcp-server/ 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](https://docs.blockvectra.com/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](https://docs.blockvectra.com/pt-br/guides/ai-agents/). ## Ferramentas | Ferramenta | O que faz | API key | Tipo de acesso | | --- | --- | --- | --- | | `read_doc` | Lê uma página da documentação em Markdown. | Não necessária | Somente leitura | | `search_docs` | Pesquisa títulos, caminhos e resumos da documentação. | Não necessária | Somente leitura | | `list_chains` | Lista as redes compatíveis, os parâmetros e as políticas de métodos (GET /v1/chains). | Não necessária | Somente leitura | | `get_status` | Lê o status em tempo real do serviço e das redes (GET /v1/status). | Não necessária | Somente leitura | | `get_pricing` | Lê os pesos de Compute Units, os parâmetros do plano gratuito e os padrões das chaves (GET /v1/plans). | Não necessária | Somente leitura | | `estimate_usage` | Estima as Compute Units e o custo de um ou mais métodos. | Não necessária | Somente leitura | | `how_to_get_api_key` | Retorna os passos para obter uma API key e as formas de autenticação das requisições. | Não necessária | Somente leitura | | `get_method_info` | Mostra a disponibilidade de um método por rede, o peso em CU e o preço. | Não necessária | Somente leitura | | `explain_error` | Consulta o significado de um erro, a cobrança, se permite nova tentativa e como se recuperar. | Não necessária | Somente leitura | | `list_docs` | Lista todas as páginas da documentação com caminho e título. | Não necessária | Somente leitura | | `rpc_call` | Executa um método JSON-RPC somente leitura em uma rede compatível. | Opcional: sem chave apenas para os métodos em public.methods da rede | Somente leitura | | `data_api_get` | Envia uma requisição GET para a Data API de uma rede compatível. | Obrigatória (cabeçalho x-api-key) | Somente leitura | | `get_account` | Lê o saldo da conta, as CU e os limites de taxa (GET /v1/account). | Obrigatória (cabeçalho x-api-key) | Somente leitura | | `get_deposit_address` | Lê o endereço de depósito da conta, as redes abertas e os tokens. | Obrigatória (cabeçalho x-api-key) | Somente leitura | | `send_raw_transaction` | Transmite uma transação bruta já assinada (eth_sendRawTransaction). | Opcional: sem chave apenas para os métodos em public.methods da rede | Transmite uma transação assinada | 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](https://docs.blockvectra.com/pt-br/guides/programmatic-signup/?ref=docs-mcp-server). ## 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: ```bash 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: ```bash 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): ```json { "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`): ```bash 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](https://code.claude.com/docs/en/mcp). ### Cursor Adicione o servidor à configuração de MCP do Cursor: ```json { "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"}`): ```text 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: ```json { "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](https://cursor.com/docs/context/mcp) e [links de instalação do Cursor](https://cursor.com/docs/context/mcp/install-links). ### VS Code No VS Code, configure o servidor em `.vscode/mcp.json` sob a chave de nível superior `servers` com `type: "http"`: ```json { "servers": { "blockvectra": { "type": "http", "url": "https://docs.blockvectra.com/mcp" } } } ``` Quando precisar de ferramentas autenticadas, adicione o objeto `headers`: ```json { "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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) e [referência de configuração MCP do VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ### Codex Adicione o servidor usando a CLI do OpenAI Codex: ```bash codex mcp add blockvectra --url https://docs.blockvectra.com/mcp ``` Em `config.toml`, configure a URL do servidor: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" ``` Quando precisar de ferramentas autenticadas, configure os cabeçalhos de requisição em `config.toml`: ```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: ```toml [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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Gemini CLI Na configuração da Gemini CLI, adicione o servidor sob `mcpServers` usando `httpUrl` para Streamable HTTP: ```json { "mcpServers": { "blockvectra": { "httpUrl": "https://docs.blockvectra.com/mcp" } } } ``` Quando precisar de ferramentas autenticadas, adicione o objeto `headers` com sua API key: ```json { "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](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md). ### OpenAI Responses API Ao chamar a OpenAI Responses API, passe o servidor MCP no array `tools` com `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": "..." }' ``` Quando precisar de ferramentas autenticadas, inclua o campo `headers` na definição da ferramenta: ```json { "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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) e [referência da OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create). ### Windsurf No Windsurf, configure o servidor sob `mcpServers` usando o campo `serverUrl`: ```json { "mcpServers": { "blockvectra": { "serverUrl": "https://docs.blockvectra.com/mcp" } } } ``` Quando precisar de ferramentas autenticadas, adicione o objeto `headers` com sua API key: ```json { "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](https://docs.devin.ai/desktop/cascade/mcp). ### 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: ```text 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](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). ### 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: ```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 ``` 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: ```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":[]}}}' ``` 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: ```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":{}}}' ``` 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](https://docs.blockvectra.com/pt-br/guides/programmatic-signup/?ref=docs-mcp-server), 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](https://docs.blockvectra.com/pt-br/errors/) para ver se uma falha é cobrada e se vale tentar novamente. ## Relacionados * [Conectar agentes de IA](https://docs.blockvectra.com/pt-br/guides/ai-agents/): arquivos legíveis por máquina, endpoints JSON públicos e o fluxo de seleção de redes. * [Cadastro programático](https://docs.blockvectra.com/pt-br/guides/programmatic-signup/?ref=docs-mcp-server): crie uma API key com uma assinatura de carteira, sem navegador. * [Receitas de frameworks de agentes](https://docs.blockvectra.com/pt-br/guides/agent-frameworks/): ElizaOS, viem, wagmi e Coinbase AgentKit. * [Códigos de erro](https://docs.blockvectra.com/pt-br/errors/): todos os erros com regras de cobrança e de nova tentativa.