MCP

Nordvec sirve el Model Context Protocol (MCP), por lo que un agente o asistente que hable MCP puede descubrir las operaciones de tu espacio de trabajo como herramientas y llamarlas de forma nativa, sin necesidad de un documento OpenAPI para razonar sobre ellas.

Hay dos servidores:

Ambos se ejecutan en la UE, en la misma infraestructura que el resto de la API.

Conectar un cliente

Apunta un cliente MCP al servidor de la base de conocimiento con tu clave API como token portador. La mayoría de los clientes aceptan un bloque de configuración como este:

{
  "mcpServers": {
    "nordvec": {
      "url": "https://nordvec.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer nv_your_api_key"
      }
    }
  }
}

El servidor es HTTP Streamable sin estado: cada mensaje es un POST que transporta una solicitud JSON-RPC, y la respuesta llega en el cuerpo de la respuesta. No hay sesiones que mantener ni flujos iniciados por el servidor, por lo que un GET en la URL responde 405, y un POST cuyo Content-Type no es application/json responde 415 antes de leer el cuerpo.

El servidor se autentica con una clave estática portadora y no ofrece descubrimiento OAuth. Un cliente que te permita establecer encabezados de solicitud (agentes de codificación, extensiones de IDE, el Inspector MCP en modo de encabezado) se conecta como se muestra arriba; un cliente alojado que solo admite el flujo de autorización OAuth no puede conectarse todavía.

Un cliente que envía el encabezado MCP-Protocol-Version recibe respuesta bajo esa versión cuando el servidor la admite (2025-06-18 y 2024-11-05) y es rechazado con 400 cuando no es así, por lo que un desajuste de versión se informa en el primer mensaje en lugar de como una respuesta mal formada más tarde.

Herramientas

Las herramientas se derivan de la API REST, una herramienta por operación que una clave API puede llamar. El nombre de una herramienta es la ruta SDK de la operación en snake case, con un segmento que repite el anterior eliminado:

tools/list es el catálogo autoritativo: muestra una clave solo las herramientas que admiten sus ámbitos, y la descripción de cada herramienta nombra el ámbito que requiere. El inputSchema de una herramienta es el esquema de solicitud de la operación y, cuando la operación devuelve un objeto, su outputSchema es el esquema de respuesta y los resultados llevan structuredContent junto al texto JSON.

Llamar a una herramienta que los ámbitos de la clave no admiten responde con un error de herramienta que nombra FORBIDDEN, el mismo rechazo que da la ruta REST, por lo que un cliente que mantiene una lista en caché de otra clave entiende el motivo en lugar de simplemente que la herramienta falta.

Límites y errores

Una llamada a una herramienta consume el mismo cubo de límite de frecuencia que la operación REST a la que corresponde, y cualquier otro mensaje en el punto final consume su propio cubo. Los encabezados X-RateLimit-*, la respuesta 429 con su Retry-After, y el sobre de error son los mismos que en la API REST, por lo que un cliente que ya los maneja para REST los maneja aquí también.

Una llamada a una herramienta fallida devuelve un resultado de herramienta MCP con isError: true cuyo texto es el cuerpo de error REST (code, message, data); los fallos de validación llevan la misma forma fieldErrors que devuelve la API REST. Un error JSON-RPC está reservado para el protocolo en sí: un cuerpo no analizable, un método desconocido o un fallo del servidor.

Los cuerpos de las solicitudes están limitados a 1 MB, el mismo límite que las rutas REST.

Un primer intercambio

# Discover the tools your key can call
curl https://nordvec.com/api/v1/mcp \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search the workspace
curl https://nordvec.com/api/v1/mcp \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"documents_search","arguments":{"query":"data retention policy"}}}'

El servidor de documentación

El servidor de documentación en /api/mcp no necesita clave. Ofrece list_guides, get_guide, search_docs y list_connectors, por lo que un agente que está construyendo una integración puede leer estas guías directamente. Está limitado por IP como los otros puntos finales públicos.