Servidor MCP — Instalación

Qué es esto

Instrucciones de configuración para conectar un asistente de IA a ComStack mediante el servidor MCP. OAuth 2.1 es el estándar para usuarios humanos; las cabeceras API-key están disponibles para servicios headless y pipelines de CI.

Cómo funciona

OAuth (recomendado — usuarios humanos)

OAuth 2.1 con Dynamic Client Registration es el estándar para Claude, Cursor y otros clientes MCP compatibles con OAuth. El flujo es:

1. Añade https://api.comstack.ai/mcp como servidor MCP personalizado en tu cliente.
2. El cliente descubre automáticamente OAuth mediante /.well-known/oauth-authorization-server.
3. El cliente se registra automáticamente: no requiere pasos manuales.
4. Se abre una ventana emergente para iniciar sesión con Google en tu cuenta de ComStack.
5. El cliente recibe tokens de acceso y actualización. Los tokens se rotan automáticamente; si la cadena de actualización se rompe, se te pedirá iniciar sesión de nuevo.

API keys (servicios headless)

Para pipelines de CI y servicios automatizados, utiliza las cabeceras x-api-key y x-project-id con una API key de servicio (key_type: "service"). Las API keys personales están obsoletas para su uso en MCP.

Cuándo usarlo

Sigue el flujo de OAuth si conectas un asistente de IA de forma interactiva (Claude web, Claude Desktop, Cursor). Usa API keys cuando necesites acceso desatendido, de servidor a servidor.

Parámetros / campos / entradas

Conectar Claude (web, escritorio o móvil)

La forma más rápida es a través de la página de cuenta. Para una configuración manual en Claude:

1. Ve a Customize → Connectors.
2. Haz clic en Add custom connector.
3. Introduce Name: ComStack y Server URL: https://api.comstack.ai/mcp.
4. Haz clic en Connect e inicia sesión con Google cuando aparezca la ventana emergente.
5. Listo: abre cualquier chat nuevo para usar ComStack.

Conectar mediante API key (headless)

curl -X POST https://api.comstack.ai/mcp \
  -H "Content-Type: application/json" \
  -H "x-project-id: <your-project-id>" \
  -H "x-api-key: <your-service-key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get-project-state",
      "arguments": { "project_id": "<your-project-id>" }
    }
  }'

El project_id dentro de arguments debe coincidir con el proyecto vinculado a la clave. Los errores de coincidencia devolverán InvalidRequest.

Modo stdio local (solo desarrollo)

El modo stdio se ejecuta localmente con acceso directo a la base de datos: no requiere OAuth ni API keys. project_id toma por defecto el valor de la variable de entorno cuando se omite en las llamadas a herramientas. No apto para producción.

Ejemplo

Verificación de la conexión tras la configuración:

Pregunta al asistente de IA: “¿Quién soy en ComStack?” — el asistente llamará a whoami y devolverá tu identidad autenticada y los proyectos accesibles. Si devuelve un error, comprueba que la URL del servidor sea exactamente https://api.comstack.ai/mcp y que el paso de inicio de sesión de Google se haya completado con éxito.

Errores comunes

Error	Causa	Solución
El conector muestra “Disconnected”	Sesión OAuth expirada o cadena de actualización rota	Elimina y vuelve a añadir el conector
403 origin not allowed	Solicitud enviada desde un origen no listado	Usa el endpoint de producción; no añadidas cabeceras Origin personalizadas
InvalidRequest	API key vinculada al proyecto incorrecto	Comprueba que x-project-id coincida con el alcance del proyecto de la clave
401 Unauthorized	Token expirado o revocado	Vuelve a autenticarte
429 Too Many Requests	Límite de tasa excedido (30/min en rutas OAuth, 60/min en /mcp)	Espera e inténtalo de nuevo

Relacionado

• Visión general del servidor MCP — transporte, enrutamiento y límites de tasa
• Herramientas — herramientas disponibles y requisitos de rol
• Seguridad — detalles de OAuth y modelo de amenazas