Ir al contenido
ComStack

Primeros pasos con el servidor MCP

Qué es esto

El punto de entrada humano: conecta el servidor MCP a tu asistente, confirma que funciona y ejecuta tu primera publicación mediante prompts de copiar y pegar, idealmente en un proyecto de prueba desechable para que nada llegue a un sitio en vivo por accidente.

Cómo funciona

El servidor se ejecuta en https://api.comstack.ai/mcp a través de HTTP con soporte para streaming. Las personas se conectan mediante OAuth (inicio de sesión en el navegador); las máquinas utilizan encabezados de clave API. Una vez conectado, las herramientas aparecen en tu cliente y cada llamada está limitada por un project_id que pasas explícitamente.

Conecta tu cliente

La vía más rápida para todos es la página de Cuenta: su pestaña de Conectores ofrece una configuración con un solo clic para Claude (web/escritorio/móvil), ChatGPT, la extensión de Chrome y Claude Code, con campos para copiar y pegar y un indicador de conexión en tiempo real.

Configuración manual, por cliente:

Claude (web, escritorio, móvil)

  1. Abre Customize → Connectors → Add custom connector.
  2. Introduce el Name ComStack y la Server URL https://api.comstack.ai/mcp.
  3. Haz clic en Connect e inicia sesión con Google cuando se abra la ventana emergente.
  4. El servidor aparecerá en cualquier conversación nueva: abre el menú +, elige Connectors y activa ComStack.

ChatGPT

ChatGPT se conecta a servidores MCP remotos a través del Developer mode, en planes de pago (Plus, Pro, Business, Enterprise o Edu; no disponible en la versión gratuita).

  1. En ChatGPT, abre Settings → Apps & Connectors (a veces etiquetado como Connectors) → Advanced settings y activa Developer mode. En Business, Enterprise o Edu, un administrador debe habilitarlo primero en Settings → Permissions & Roles → Connected Data.
  2. De vuelta en Apps & Connectors, haz clic en Create (a veces Create app o Add custom connector).
  3. Introduce el Name ComStack y la MCP Server URL https://api.comstack.ai/mcp, establece la Authentication en OAuth y marca I trust this application.
  4. Haz clic en Create e inicia sesión con Google cuando se abra la ventana emergente.
  5. Úsalo en un chat: + → More → Developer mode → ComStack.

OpenAI está renombrando estos menús (de connectors a apps), por lo que las etiquetas pueden variar ligeramente; la ruta es la misma.

Claude Code

Terminal window
claude mcp add --transport http ComStack https://api.comstack.ai/mcp

Acceso de máquina (CI, claves API)

Para automatización sin inicio de sesión en navegador, autentícate con encabezados en lugar de OAuth:

Terminal window
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"}}}'

Utiliza una clave API de tipo service (genérala en la configuración del proyecto); el project_id en cada llamada debe coincidir con el encabezado x-project-id. Las claves personales están obsoletas para el endpoint MCP.

Primera ejecución

  1. Elige un espacio de trabajo. Experimenta en un proyecto de prueba nuevo (la herramienta create-project o la página de Cuenta) para que las primeras ejecuciones no afecten a ningún sitio en vivo.
  2. Confirma la conexión. Pide al asistente que llame a whoami y list-my-projects: deberías ver tu cuenta y el proyecto, junto con tu rol.
  3. Instantánea. Haz que llame a get-project-state para tu project_id; lee el recurso transformento://guide (o get-guide) para conocer el flujo de trabajo completo.
  4. Redacta, aprueba, publica con los prompts a continuación: nada se publica hasta que apruebes un manifiesto de publish y el asistente ejecute publish-confirm.

Ejemplos de prompts

Pégalos en un asistente conectado (te pedirá o inferirá tu project_id):

  1. Inventario — “Conéctate a mi proyecto de ComStack <PROJECT_ID> y enumera mis páginas en vivo y borradores.”
  2. Crear una página — “Crea una página de conocimiento en el slug docs/hello titulada ‘Hello from MCP’ con una breve introducción. Muéstrame el borrador antes de publicar.”
  3. Editar una página — “Actualiza la página en el slug docs/hello para añadir una sección de ‘Próximos pasos’, luego muéstrame la URL del borrador.”
  4. Publicar — “Publica mis borradores. Muéstrame el manifiesto primero y espera mi visto bueno, luego confirma y dame los enlaces en vivo.”
  5. Limpiar — “Descarta el borrador en la ruta <DRAFT_PATH>: no quiero publicarlo.”

Un buen asistente siempre presenta el manifiesto de publish y la URL del borrador, esperando tu aprobación explícita antes de llamar a publish-confirm.

Usa un proyecto de prueba

Dado que publish promociona todos los borradores pendientes de un proyecto a la vez, realiza tus primeras ejecuciones en un proyecto de prueba dedicado: crea uno con create-project, verifica las URLs publicadas en el site_url de ese proyecto y solo apunta el asistente a un proyecto de producción una vez que el flujo sea predecible.

Errores comunes

  • Ventana emergente de OAuth bloqueada — permite ventanas emergentes para api.comstack.ai y vuelve a conectar.
  • Desajuste de x-project-id — con claves API, el project_id en cada llamada debe ser igual al encabezado x-project-id.
  • Herramienta no disponible / rol incorrecto — la publicación requiere el rol manager; confírmalo mediante list-my-projects.
  • project_name does not match — el asistente lo adivinó; dile que lea el nombre desde get-project-state.
  • Nada se publicó tras publish — publish es solo una prueba; el asistente también debe ejecutar publish-confirm y consultar publish-status.

Relacionado

Última actualización: