MCP

Cada tenant tiene su propio servidor MCP (Model Context Protocol) — un endpoint que expone tu conocimiento indexado como una tool (search_knowledge) para que cualquier cliente MCP compatible (Claude Desktop, Claude Code, Cursor, tu propio agente) lo consulte con trazabilidad de fuente.

Crear un endpoint

Requiere JWT y rol admin. La API key se genera y se muestra una sola vez en esta respuesta — Kelova solo guarda el hash (bcrypt), nunca el valor en texto plano.

curl -X POST https://api.kelova.app/tenants/me/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Desktop",
    "description": "Conector para el equipo de soporte"
  }'

Respuesta (201):

{
  "endpoint": {
    "id": "e1f2a3...",
    "tenant_id": "t9f8e7...",
    "name": "Claude Desktop",
    "description": "Conector para el equipo de soporte",
    "api_key_prefix": "kva_7f3d",
    "hosted": true,
    "status": "active",
    "total_queries": 0,
    "created_at": "2026-07-10T09:00:00Z",
    "endpoint_url": "https://api.kelova.app/mcp/tuempresa"
  },
  "api_key": "kva_7f3d9c1e2b4a5f6d8e0c1a2b3c4d5e6f"
}

Copia api_key de inmediato — la respuesta de este endpoint es la única vez que Kelova lo revela. Si lo pierdes, la única opción es rotarlo (abajo); no existe un endpoint para "ver la key actual".

Listar endpoints

curl https://api.kelova.app/tenants/me/mcp \
  -H "Authorization: Bearer <token>"

{
  "endpoints": [
    {
      "id": "e1f2a3...",
      "tenant_id": "t9f8e7...",
      "name": "Claude Desktop",
      "api_key_prefix": "kva_7f3d",
      "hosted": true,
      "status": "active",
      "total_queries": 128,
      "last_used_at": "2026-07-10T08:30:00Z",
      "created_at": "2026-07-01T09:00:00Z",
      "endpoint_url": "https://api.kelova.app/mcp/tuempresa"
    }
  ]
}

api_key_prefix es lo único que se puede mostrar de la key después de crearla — úsalo para que el usuario identifique cuál endpoint es cuál.

Rotar la key

curl -X POST https://api.kelova.app/tenants/me/mcp/rotate-key \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_id": "e1f2a3..."}'

{
  "endpoint_id": "e1f2a3...",
  "api_key": "kva_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

La key anterior queda invalidada de inmediato. Igual que en la creación, este valor solo se muestra una vez.

Analytics de uso

curl "https://api.kelova.app/tenants/me/mcp/analytics?period=30d" \
  -H "Authorization: Bearer <token>"

period acepta 7d, 30d (default), 90d.

{
  "period_days": 30,
  "total_requests": 842,
  "latency_p50_ms": 210,
  "latency_p95_ms": 640,
  "total_tokens_in": 15200,
  "total_tokens_out": 48300,
  "overage_requests": 0,
  "by_endpoint": [
    { "endpoint_id": "e1f2a3...", "requests": 842, "latency_p50_ms": 210 }
  ]
}

Nunca incluye el texto de las queries ni de las respuestas — solo metadata agregada.

Conectar el servidor MCP

El endpoint MCP vive en https://api.kelova.app/mcp/{tenant_slug} (el mismo endpoint_url que devuelve la API) y habla JSON-RPC 2.0 sobre HTTP. La autenticación es por API key en el header Authorization: Bearer <api_key> — no es un JWT de usuario.

Agrega este bloque a tu mcp.json (por ejemplo .cursor/mcp.json):

{
  "mcpServers": {
    "kelova": {
      "url": "https://api.kelova.app/mcp/tuempresa",
      "headers": {
        "Authorization": "Bearer <TU_API_KEY>"
      }
    }
  }
}

Claude Desktop y Claude Code no usan mcp.json para servidores remotos HTTP — agrega la URL como conector personalizado (Settings → Connectors → Add custom connector), usando la misma url y el mismo header Authorization: Bearer <TU_API_KEY> que arriba.

Reemplaza <TU_API_KEY> con la key que copiaste al crear o rotar el endpoint — nunca se vuelve a mostrar (R6, arriba).

Qué expone el servidor

El servidor implementa el protocolo MCP estándar (initialize, tools/list, tools/call) y una sola tool:

Tool	Descripción
`search_knowledge`	Busca en los documentos indexados del workspace. Parámetros: `query` (string, requerido), `top_k` (integer, opcional, default 5).

Cada resultado incluye source_file, location, synced_at y similarity — la misma trazabilidad de fuente que POST /agent/query (ver Agentes).

Endpoints públicos (sin autenticación)

Útiles para health checks o para que un cliente MCP descubra las capacidades del servidor antes de conectarse:

curl https://api.kelova.app/mcp/registry-manifest
curl https://api.kelova.app/mcp/health