MCP

Datos de conexión

Antes: un token para el asistente

Creá un token aparte en Administración > API y MCP, con un nombre que diga quién lo usa (por ejemplo, «Claude Code de Ana»). Dale solo los alcances que hacen falta: para explorar y consultar alcanza con lectura.

El asistente ve únicamente las operaciones que ese token puede usar hoy. Lo que cambia queda en la Actividad de la cuenta a nombre del token y de su persona.

Claude Code

Desde la terminal, con el token en una variable de entorno:

export KAPTATIVA_TOKEN="TU_TOKEN"

claude mcp add --transport http kaptativa https://panel.kaptativa.app/api/mcp \
  --header "Authorization: Bearer $KAPTATIVA_TOKEN"

Para compartir la configuración con el equipo sin compartir el token, usá un archivo .mcp.json en la raíz del proyecto. Claude Code reemplaza ${KAPTATIVA_TOKEN} por la variable de entorno de cada persona.

{
  "mcpServers": {
    "kaptativa": {
      "type": "http",
      "url": "https://panel.kaptativa.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${KAPTATIVA_TOKEN}"
      }
    }
  }
}

Después abrí Claude Code y escribí /mcp: el servidor kaptativa tiene que aparecer conectado, con sus herramientas.

Cursor

Creá o editá .cursor/mcp.json en el proyecto (o ~/.cursor/mcp.json para todos tus proyectos) y reemplazá TU_TOKEN por el token:

{
  "mcpServers": {
    "kaptativa": {
      "url": "https://panel.kaptativa.app/api/mcp",
      "headers": {
        "Authorization": "Bearer TU_TOKEN"
      }
    }
  }
}

En la configuración de Cursor, en la parte de MCP, el servidor tiene que figurar activo con la lista de herramientas. Si el archivo queda con el token adentro, no lo subas al repositorio: sumalo a .gitignore.

Probar la conexión a mano

Si un cliente no conecta, este pedido dice si el problema es el token o el cliente. Tiene que responder la lista de herramientas.

curl -X POST "https://panel.kaptativa.app/api/mcp" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• 401: el token falta, venció o se revocó.
• 400: el encabezado MCP-Protocol-Version pide una versión que el servidor no tiene, o el cuerpo no es JSON.
• 403: la cuenta no tiene activa la API, o el pedido vino de un navegador con un encabezado Origin que no es de confianza. Los clientes que no son un navegador no mandan Origin y no pasan por ese control.
• 405: el cliente intentó abrir un flujo de eventos con GET o cerrar una sesión con DELETE. Este servidor responde solo por POST: elegí el transporte HTTP, no SSE.
• 413: el mensaje pasa los 100 KB.
• 429: se pasó el límite de uso, que es el mismo de la API.

Qué ofrece el servidor

• Una herramienta que solo lee viene marcada como de solo lectura; las demás, no. Los clientes usan esa marca para pedirte confirmación antes de un cambio: dejá esa confirmación activada.
• Cuando una herramienta se rechaza (falta un permiso, la entrada no es válida, una regla del negocio no lo deja), el asistente recibe el motivo en castellano y puede corregir el pedido.
• Las herramientas que el token no alcanza no aparecen en la lista, y llamarlas igual devuelve el motivo.
• Las respuestas llevan los mismos encabezados de cuota que la API.
• Por MCP no hay idempotencia: si el asistente repite una herramienta que crea algo, se crea dos veces.

Para usarlo con cuidado

• Un token por persona y por herramienta. Si alguien deja el equipo, se revoca el suyo y nada más.
• Empezá con alcances de lectura. Sumá escritura solo en el módulo donde el asistente tiene que hacer cambios.
• El asistente actúa con los permisos de la persona dueña del token: no le des un token de quien administra la cuenta para una tarea de consulta.
• Revisá cada tanto el registro de pedidos del token en el panel.