Servidor MCP de BlockVectra: RPC blockchain y herramientas de documentación para agentes de IA

El servidor MCP de BlockVectra en https://docs.blockvectra.com/mcp ofrece a desarrolladores y agentes de IA 15 herramientas para llamadas RPC blockchain, estado de cadenas, precios y documentación. No necesita API key para conectarse: 10 herramientas nunca la necesitan; las demás usan x-api-key de los encabezados de su cliente. Instalación en una línea: claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp

El endpoint es el endpoint MCP (POST HTTP que recibe JSON-RPC 2.0; GET devuelve 405), servido sobre MCP Streamable HTTP y sin estado. Para los archivos HTTP, el JSON público y el flujo de registro asociado, consulte Conectar agentes de IA.

Herramientas

Esta tabla se genera a partir del registro de herramientas del servidor, por lo que lista todas las herramientas que devuelve tools/list. Cada herramienta acepta los argumentos y devuelve los campos descritos en su propio esquema de tools/list.

Seguridad de la API key

Las herramientas con clave necesitan una API key para ejecutar solicitudes de la Data API, operaciones de cuenta o métodos RPC fuera de los métodos públicos de una cadena.

• Lectura estricta desde encabezados: la API key se lee únicamente de los encabezados de la solicitud HTTP del cliente MCP (x-api-key: rgw_... o Authorization: Bearer rgw_...).
• Nunca ponga claves en el chat: nunca pase API keys ni claves privadas en los argumentos de las herramientas ni las pegue en el chat. Los argumentos de las herramientas y el historial del chat pasan a los registros y contextos de la conversación; pasar claves en los argumentos será rechazado.

Si se llama sin el encabezado de API key, las herramientas con clave devuelven isError: true y dirigen al agente a how_to_get_api_key y a la guía de registro programático.

Instalar en su cliente

Puede conectarse al servidor MCP de documentación de BlockVectra en https://docs.blockvectra.com/mcp desde los entornos de desarrollo y frameworks más habituales.

Empiece sin API key. Conéctese al endpoint MCP, llame a list_chains y lea quickstart con read_doc. Añada una API key en los encabezados HTTP de su cliente cuando necesite las herramientas de la Data API o de cuenta. El acceso RPC sin clave sigue la política de métodos públicos de cada cadena.

El encabezado x-api-key es opcional. Sin API key, los clientes pueden usar todas las herramientas de documentación de solo lectura (read_doc, search_docs, list_docs), el descubrimiento de cadenas (list_chains), el estado en vivo (get_status), la estimación de precios (get_pricing, estimate_usage), las explicaciones de errores (explain_error) y los métodos permitidos en endpoints públicos. Al usar herramientas con clave (rpc_call en métodos restringidos, send_raw_transaction, data_api_get, get_account y get_deposit_address), configure el encabezado x-api-key con su API key.

Claude Code

Conéctese al servidor MCP mediante la CLI:

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

Para incluir una API key opcional en las herramientas autenticadas, pase la opción --header (o -H) y haga referencia a una variable de entorno en lugar de pegar la clave. Use comillas simples para que su shell no la expanda; Claude Code expande ${BLOCKVECTRA_API_KEY} al iniciar la sesión:

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

La misma configuración como .mcp.json a nivel de proyecto (que también es lo que escribe claude mcp add --scope project):

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

Exporte BLOCKVECTRA_API_KEY en el entorno que inicia claude. Claude Code le pide aprobar un servidor de un .mcp.json de proyecto la primera vez que ejecuta claude en ese directorio; hasta entonces claude mcp list lo muestra como Pending approval.

Para scripts y CI, pase el archivo con --mcp-config y permita las herramientas del servidor. La clave permanece en el entorno y el cliente MCP añade el encabezado por sí mismo, de modo que el agente no necesita un comando de shell que expanda $BLOCKVECTRA_API_KEY (la comprobación de permisos de Claude Code rechazaba esos comandos en modo no interactivo con Contains simple_expansion):

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

Con la clave definida, el resultado de rpc_call también contiene cu_charged y balance_units; una llamada sin clave devuelve solo la respuesta JSON-RPC. Si la variable no está definida, el cliente envía el texto literal del encabezado y el servidor responde invalid_api_key (código de error -32024) en lugar de recurrir al endpoint sin clave.

Documentación oficial: documentación MCP de Claude Code.

Cursor

Añada el servidor a la configuración MCP de Cursor:

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

Cursor también admite la instalación con un clic mediante enlaces profundos usando la configuración codificada en base64 eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9 (que representa {"url":"https://docs.blockvectra.com/mcp"}):

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

Cuando necesite herramientas autenticadas (Data API o gestión de cuenta), añada el objeto headers con su API key:

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

La forma ${env:NAME} sigue la documentación de Cursor, que resuelve variables en url y headers; esta forma no se ha ejecutado aquí contra Cursor. Coloque el archivo en .cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global).

Documentación oficial: documentación MCP de Cursor y enlaces de instalación de Cursor.

VS Code

En VS Code, configure el servidor en .vscode/mcp.json bajo la clave de nivel superior servers con type: "http":

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

Cuando necesite herramientas autenticadas, añada el objeto headers:

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

Para almacenar credenciales sensibles, VS Code permite hacer referencia a variables de entrada o archivos de entorno en lugar de escribir las claves en el archivo. También puede añadir servidores con la acción MCP: Add Server de la paleta de comandos.

Documentación oficial: documentación de servidores MCP de VS Code y referencia de configuración MCP de VS Code.

Codex

Añada el servidor con la CLI de OpenAI Codex:

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

En config.toml, configure la URL del servidor:

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

Cuando necesite herramientas autenticadas, configure los encabezados de solicitud en config.toml:

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

Como alternativa, asigne el encabezado desde una variable de entorno:

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

Documentación oficial: documentación MCP de la CLI de OpenAI Codex.

Gemini CLI

En la configuración de Gemini CLI, añada el servidor bajo mcpServers usando httpUrl para Streamable HTTP:

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

Cuando necesite herramientas autenticadas, añada el objeto headers con su API key:

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

Documentación oficial: documentación del servidor MCP de Gemini CLI.

OpenAI Responses API

Al llamar a la OpenAI Responses API, pase el servidor MCP en el array tools con 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": "..."
  }'

Cuando necesite herramientas autenticadas, incluya el campo headers en la definición de la herramienta:

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

Documentación oficial: guía de herramientas MCP de OpenAI y referencia de la OpenAI Responses API.

Windsurf

En Windsurf, configure el servidor bajo mcpServers usando el campo serverUrl:

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

Cuando necesite herramientas autenticadas, añada el objeto headers con su API key:

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

Windsurf también admite hacer referencia a variables de entorno, como "x-api-key": "${env:BLOCKVECTRA_API_KEY}".

Documentación oficial: documentación MCP de Windsurf.

Claude Desktop y claude.ai

Los conectores personalizados se configuran desde la interfaz de usuario:

• claude.ai: vaya a Customize > Connectors, haga clic en + Add, seleccione Add custom connector e introduzca la URL:

  Copiar texto

  https://docs.blockvectra.com/mcp

• Claude Desktop: abra el menú de ajustes de la cuenta y configure los conectores personalizados desde la interfaz de conectores.

Al conectarse a la URL, Claude puede buscar guías, leer documentación en Markdown, inspeccionar las cadenas compatibles, consultar el estado de la red y calcular estimaciones de precios sin credenciales.

Documentación oficial: guía de conectores personalizados de Claude.

Comprobar la conexión y resolver problemas

En Claude Code, claude mcp list muestra el estado de cada servidor. Para obtener el recuento de herramientas realmente registradas, ejecute una vez con salida en streaming y lea el evento init, o lea el registro de depuración:

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

Una conexión correcta muestra "status": "connected" y herramientas mcp__blockvectra-docs__* (como list_chains y rpc_call) en el evento init. En el registro de depuración, busque líneas sobre blockvectra-docs como Successfully connected y Failed to fetch tools. Si el servidor figura como connected pero no aparece ninguna herramienta, lea el motivo que el registro de depuración (--debug mcp) indica después de Failed to fetch tools. Para comprobar que el propio servidor funciona, use las llamadas curl siguientes.

Llamar al endpoint MCP sin cliente

El endpoint es JSON-RPC 2.0 sobre POST HTTP, por lo que cualquier cliente HTTP puede llamarlo:

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

La primera llamada devuelve la lista de herramientas; la segunda devuelve la respuesta JSON-RPC en result.structuredContent. Los identificadores de cadena son slugs como base_mainnet; obténgalos de list_chains. Las herramientas con clave necesitan el encabezado x-api-key; esta llamada lee su cuenta con la clave de una variable de entorno:

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

Devuelve key_id, plan, balance_units, balance_cu y los límites de velocidad de la clave en result.structuredContent. Si su agente ejecuta comandos mediante un shell con control de permisos, esa expansión de variable puede bloquearse; configure el encabezado en el cliente MCP.

FAQ

¿Necesita el servidor MCP de BlockVectra una API key?

No. Conectarse no requiere clave, y 10 de las 15 herramientas nunca la necesitan. rpc_call y send_raw_transaction se ejecutan sin clave solo para los métodos de public.methods de la cadena (léalos con list_chains). data_api_get, get_account y get_deposit_address necesitan el encabezado x-api-key.

¿Puede el servidor MCP crear o revocar API keys?

No. Ninguna herramienta crea, lista ni revoca API keys. how_to_get_api_key solo devuelve los pasos; un agente crea una clave por HTTP siguiendo el registro programático, y las personas la crean en la consola. Las claves nunca pasan por los argumentos de las herramientas.

¿Puede un agente enviar transacciones a través del servidor MCP?

Puede difundirlas, no firmarlas. rpc_call rechaza los métodos de escritura como eth_sendRawTransaction, eth_sendTransaction, eth_sign y personal_*. send_raw_transaction difunde con eth_sendRawTransaction una transacción que usted ya firmó localmente; el servidor nunca conserva ni ve una clave privada.

¿Qué ocurre cuando falla una llamada?

Los errores de las herramientas devuelven isError: true con un motivo estructurado. Use explain_error o la referencia de códigos de error para ver si un fallo se factura y si conviene reintentar.

Páginas relacionadas

• Conectar agentes de IA: archivos legibles por máquinas, endpoints JSON públicos y el flujo de selección de cadena.
• Registro programático: cree una API key con una firma de billetera, sin navegador.
• Recetas para frameworks de agentes: ElizaOS, viem, wagmi y Coinbase AgentKit.
• Códigos de error: cada error con sus reglas de facturación y reintento.