Saltearse al contenido

MCP para agentes de IA

Cada base de datos de NamiDB Cloud tiene un endpoint de Model Context Protocol, así que un agente de IA o un asistente de programación puede leer su esquema y ejecutar Cypher como herramientas. No hay nada que instalar: es un servidor MCP remoto sobre HTTPS.

https://db.namidb.com/v1/<database>/mcp

Autentícate con una API key como bearer token:

Authorization: Bearer nmdb_live_…

Herramientas

HerramientaEntradaQué hace
schemaningunaDevuelve los labels, tipos de relación, constraints e índices de la base de datos
queryquery (Cypher), params (objeto, opcional)Ejecuta una sentencia y devuelve {columns, rows, write_outcome?}

Las herramientas tienen alcance sobre la base de datos de la URL. Con una key de solo lectura, query rechaza las escrituras (y se anuncia como de solo lectura, para que los clientes puedan mostrarlo), que es lo que la mayoría de los agentes debería recibir.

Los fallos de las herramientas (un error de Cypher, un límite de uso, un timeout) vuelven como resultados de la herramienta con isError: true y el JSON del error como texto, para que el agente pueda leer el motivo y corregir su consulta. Los errores de autenticación y de base de datos son errores HTTP.

Configura un cliente

Primero crea una key: API keys → Create key, Read only, con alcance sobre la única base de datos que necesita el agente, y con vencimiento.

Claude Code

Ventana de terminal
claude mcp add --transport http namidb-movies https://db.namidb.com/v1/movies/mcp \
--header "Authorization: Bearer $NAMIDB_API_KEY"

Clientes que se configuran con JSON

La mayoría de los clientes que soportan servidores remotos (Streamable HTTP) aceptan un bloque como este; revisa la documentación de tu cliente para saber el nombre del archivo y de las claves:

{
"mcpServers": {
"namidb-movies": {
"url": "https://db.namidb.com/v1/movies/mcp",
"headers": { "Authorization": "Bearer nmdb_live_…" }
}
}
}

Desde tu propio agente

Cualquier librería cliente de MCP que hable Streamable HTTP funciona. Para probarlo con curl:

Ventana de terminal
curl https://db.namidb.com/v1/movies/mcp \
-H "Authorization: Bearer $NAMIDB_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "query", "arguments": {"query": "MATCH (m:Movie) RETURN count(m) AS movies"}}}'

Detalles del protocolo

  • Transporte: Streamable HTTP, solo POST, respuestas JSON. El endpoint no tiene estado: no hay id de sesión ni stream de server-sent events (GET y DELETE responden 405).
  • Métodos: initialize, ping, tools/list, tools/call.
  • Revisiones del protocolo 2025-06-18 (preferida), 2025-03-26 y 2024-11-05. Se aceptan lotes JSON-RPC (hasta 32 mensajes) de clientes 2025-03-26.
  • Los límites, la medición, las IP allowlists y el spend cap aplican exactamente igual que en la API HTTP: cada llamada a query es una petición.

Mantener seguros a los agentes

  • Da a los agentes keys de solo lectura salvo que tengan que escribir, y limita cada key a las bases de datos que necesita.
  • Agrega un vencimiento, y una IP allowlist cuando el agente se ejecuta desde direcciones conocidas.
  • Usa una key distinta por agente o herramienta, para poder ver el uso de cada uno y revocarlo por separado.
  • Los agentes pueden escribir consultas costosas: el timeout de consulta y los límites de uso del plan las acotan, y la pestaña Activity de la consola puede cancelar una sentencia descontrolada.

Para ejecutar un servidor MCP junto a un motor self-hosted, consulta namidb-mcp.