Comuna · Integraciones · MCP

Un servidor, cualquier cliente MCP

Comuna expone sus datos y operaciones como servidor Model Context Protocol. Claude y ChatGPT lo usan a través de sus UIs nativas; cualquier otro cliente MCP-capable (agente custom, framework, script) puede usar el mismo endpoint.

Qué es MCP

El Model Context Protocol (MCP) es un estándar abierto publicado por Anthropic a finales de 2024 para conectar modelos IA con herramientas y fuentes de datos. Está basado en HTTP, usa OAuth para auth, y expone capabilities como un catálogo descubrible de "herramientas" (funciones que el modelo puede llamar) y "recursos" (datos solo-lectura).

Claude fue el primer cliente mayor en adoptarlo. OpenAI agregó soporte en 2025. Google, Cursor y varios frameworks de agentes (LangChain, LlamaIndex) lo tienen en sus roadmaps o ya enviando.

El resultado es construye una vez, funciona en todos lados. Comuna no mantiene una integración separada por cada vendor IA — mantenemos un servidor MCP, y cada cliente que soporte MCP puede usarlo.

Endpoint MCP de Comuna

  • URL del servidor: https://api.comuna.work/mcp
  • Autenticación: OAuth2 (Supabase OAuth Server). La primera vez que un cliente se conecta, pasas por un flujo de aprobación y autorizas el cliente con tu cuenta de Comuna. Después, el cliente recibe un Bearer token que usa para cada llamada.
  • Versión del protocolo: spec MCP más reciente
  • Espejo REST: las mismas operaciones también expuestas en https://api.comuna.work/api/v1/* si necesitas JSON plano sin el framing de MCP.

Catálogo de herramientas (unas 80 herramientas)

Una lista no exhaustiva de lo que tu cliente IA puede llamar:

Boards

list_boards, get_board, create_board, update_board, delete_board

Columnas

create_column, update_column, delete_column

Cards

list_cards, get_card, create_card, update_card, move_card, complete_card, delete_card, search_cards, propose_card

Queries de tareas

get_my_tasks_today, get_my_tasks_week, get_overdue_tasks

Labels, asignados, fechas, dependencias, checklists, componentes, adjuntos

~25 herramientas cubriendo todas las operaciones a nivel de card.

Conocimiento

create_note, update_note, create_wiki_page, update_wiki_page, create_goal, create_key_result, create_project_milestone

Chat & DMs

list_channels, get_channel_messages, send_message, start_dm, send_dm

Canvas (artefactos HTML interactivos)

list_canvases, create_canvas, update_canvas, restore_canvas_version

Coordinación

get_my_context (bootstrap — llama primero), report_progress, request_human_review, answer_review, update_coworker_task, get_attention_items

Identidad

register_agent, get_my_agent_identity (para que la IA firme sus acciones con su propio avatar)

El esquema completo de cada herramienta (parámetros de entrada, shape de retorno) está disponible en el spec OpenAPI en https://api.comuna.work/openapi.yaml y vía discovery MCP estándar (tools/list).

Construir un cliente custom

Si quieres conectar Comuna a algo que no es Claude ni ChatGPT — tu propio framework de agentes, un CLI, un job CI que actualice cards automáticamente — aquí el camino corto:

  1. Dance OAuth: registra tu cliente en el endpoint well-known, lleva al usuario por la aprobación, obtén un Bearer token.
  2. Descubre herramientas: POST /mcp con tools/list para obtener el catálogo.
  3. Llama herramientas: POST /mcp con tools/call, pasando el nombre de la herramienta y los argumentos. Las respuestas incluyen el resultado y coaching hints opcionales para el modelo.
  4. Bootstrap: siempre llama get_my_context primero en cualquier nueva sesión. Devuelve las instrucciones permanentes del usuario, tareas pendientes, y reviews recientes — el estado que la IA necesita para actuar con sentido.
  5. Heartbeat + escala: llama report_progress periódicamente (cada 30–60s) durante trabajo largo; llama request_human_review antes de cualquier decisión que el humano debería tomar.

El código del servidor MCP de Comuna está en el mismo repositorio que la app, bajo mcp-server/.

Por qué apostamos por MCP

Cuando empezamos a construir la integración IA de Comuna, consideramos tres opciones:

  1. SDK LLM nativo por vendor (Anthropic SDK + OpenAI SDK + Google SDK + …). Vendor lock-in por cada uno. Schema por mantener por cada uno. Ciclo de release por cada uno.
  2. Webhook + JSON RPC custom. Nosotros tendríamos el protocolo; cada cliente necesitaría un adapter bespoke. El costo caería en el usuario.
  3. MCP (entonces nuevito, diciembre 2024).

MCP es la apuesta. Un servidor, lista creciente de clientes, spec abierto, sin carga de mantenimiento por vendor. La desventaja es que algunos clientes todavía no tienen UIs MCP pulidas (Gemini, Cursor). Es un costo temporal que aceptamos a cambio de no mantener tres integraciones distintas.

Ve la página del compañero IA para el contexto de producto, o elige un cliente para conectar.

Relacionado

  • Integraciones — Comuna habla con tus clientes IA vía MCP. Claude y ChatGPT están conectados hoy; Gemini y Cursor siguen. OAuth, sin API keys, sin plugins.
  • Integraciones · Claude — Cómo añadir Claude (Anthropic) como compañero real en tus boards de Comuna. OAuth, sin API keys, sin plugins. El plan gratis de Claude funciona.
  • Integraciones · ChatGPT — Cómo añadir ChatGPT (OpenAI) como compañero real en tus boards de Comuna. OAuth, sin API keys, sin plugins. Requiere ChatGPT Plus / Pro.
Prueba Comuna — gratis para siempre ← Volver al inicio