# Servidor MCP de BlockVectra: RPC blockchain y herramientas de documentación para agentes de IA > Source: https://docs.blockvectra.com/es/guides/mcp-server/ 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](https://docs.blockvectra.com/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](https://docs.blockvectra.com/es/guides/ai-agents/). ## Herramientas | Herramienta | Qué hace | API key | Tipo de acceso | | --- | --- | --- | --- | | `read_doc` | Lee una página de la documentación como Markdown. | No necesaria | Solo lectura | | `search_docs` | Busca en títulos, rutas y resúmenes de la documentación. | No necesaria | Solo lectura | | `list_chains` | Lista las cadenas compatibles, sus parámetros y las políticas de métodos (GET /v1/chains). | No necesaria | Solo lectura | | `get_status` | Lee el estado en vivo del servicio y de las cadenas (GET /v1/status). | No necesaria | Solo lectura | | `get_pricing` | Lee los pesos de Compute Units, los parámetros del plan gratuito y los valores predeterminados de las claves (GET /v1/plans). | No necesaria | Solo lectura | | `estimate_usage` | Estima las Compute Units y el coste de uno o varios métodos. | No necesaria | Solo lectura | | `how_to_get_api_key` | Devuelve los pasos para obtener una API key y las formas de autenticar las solicitudes. | No necesaria | Solo lectura | | `get_method_info` | Muestra la disponibilidad de un método por cadena, su peso en CU y su precio. | No necesaria | Solo lectura | | `explain_error` | Consulta el significado de un error, su facturación, si es reintentable y cómo recuperarse. | No necesaria | Solo lectura | | `list_docs` | Lista todas las páginas de la documentación con su ruta y título. | No necesaria | Solo lectura | | `rpc_call` | Ejecuta un método JSON-RPC de solo lectura en una cadena compatible. | Opcional: sin clave solo para los métodos de public.methods de la cadena | Solo lectura | | `data_api_get` | Envía una solicitud GET a la Data API de una cadena compatible. | Necesaria (encabezado x-api-key) | Solo lectura | | `get_account` | Lee el saldo de la cuenta, las CU y los límites de tasa (GET /v1/account). | Necesaria (encabezado x-api-key) | Solo lectura | | `get_deposit_address` | Lee la dirección de depósito de la cuenta, las redes abiertas y los tokens. | Necesaria (encabezado x-api-key) | Solo lectura | | `send_raw_transaction` | Difunde una transacción sin procesar ya firmada (eth_sendRawTransaction). | Opcional: sin clave solo para los métodos de public.methods de la cadena | Difunde una transacción firmada | 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](https://docs.blockvectra.com/es/guides/programmatic-signup/?ref=docs-mcp-server). ## 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: ```bash 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: ```bash 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`): ```json { "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`): ```bash 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](https://code.claude.com/docs/en/mcp). ### Cursor Añada el servidor a la configuración MCP de Cursor: ```json { "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"}`): ```text 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: ```json { "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](https://cursor.com/docs/context/mcp) y [enlaces de instalación de Cursor](https://cursor.com/docs/context/mcp/install-links). ### VS Code En VS Code, configure el servidor en `.vscode/mcp.json` bajo la clave de nivel superior `servers` con `type: "http"`: ```json { "servers": { "blockvectra": { "type": "http", "url": "https://docs.blockvectra.com/mcp" } } } ``` Cuando necesite herramientas autenticadas, añada el objeto `headers`: ```json { "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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) y [referencia de configuración MCP de VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ### Codex Añada el servidor con la CLI de OpenAI Codex: ```bash codex mcp add blockvectra --url https://docs.blockvectra.com/mcp ``` En `config.toml`, configure la URL del servidor: ```toml [mcp_servers.blockvectra] url = "https://docs.blockvectra.com/mcp" ``` Cuando necesite herramientas autenticadas, configure los encabezados de solicitud en `config.toml`: ```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: ```toml [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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Gemini CLI En la configuración de Gemini CLI, añada el servidor bajo `mcpServers` usando `httpUrl` para Streamable HTTP: ```json { "mcpServers": { "blockvectra": { "httpUrl": "https://docs.blockvectra.com/mcp" } } } ``` Cuando necesite herramientas autenticadas, añada el objeto `headers` con su API key: ```json { "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](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md). ### OpenAI Responses API Al llamar a la OpenAI Responses API, pase el servidor MCP en el array `tools` con `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": "..." }' ``` Cuando necesite herramientas autenticadas, incluya el campo `headers` en la definición de la herramienta: ```json { "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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) y [referencia de la OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create). ### Windsurf En Windsurf, configure el servidor bajo `mcpServers` usando el campo `serverUrl`: ```json { "mcpServers": { "blockvectra": { "serverUrl": "https://docs.blockvectra.com/mcp" } } } ``` Cuando necesite herramientas autenticadas, añada el objeto `headers` con su API key: ```json { "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](https://docs.devin.ai/desktop/cascade/mcp). ### 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: ```text 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](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). ### 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: ```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 ``` 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: ```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":[]}}}' ``` 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: ```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":{}}}' ``` 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](https://docs.blockvectra.com/es/guides/programmatic-signup/?ref=docs-mcp-server), 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](https://docs.blockvectra.com/es/errors/) para ver si un fallo se factura y si conviene reintentar. ## Páginas relacionadas * [Conectar agentes de IA](https://docs.blockvectra.com/es/guides/ai-agents/): archivos legibles por máquinas, endpoints JSON públicos y el flujo de selección de cadena. * [Registro programático](https://docs.blockvectra.com/es/guides/programmatic-signup/?ref=docs-mcp-server): cree una API key con una firma de billetera, sin navegador. * [Recetas para frameworks de agentes](https://docs.blockvectra.com/es/guides/agent-frameworks/): ElizaOS, viem, wagmi y Coinbase AgentKit. * [Códigos de error](https://docs.blockvectra.com/es/errors/): cada error con sus reglas de facturación y reintento.