Comuna · Integrações · MCP

Um servidor, qualquer client MCP

A Comuna expõe seus dados e operações como servidor Model Context Protocol. Claude e ChatGPT usam pelos UIs nativos; qualquer outro client MCP-capable (agente custom, framework, script) pode usar o mesmo endpoint.

O que é MCP

O Model Context Protocol (MCP) é um padrão aberto publicado pela Anthropic no fim de 2024 pra conectar modelos IA com ferramentas e fontes de dados. É baseado em HTTP, usa OAuth pra auth, e expõe capabilities como um catálogo descobrível de "ferramentas" (funções que o modelo pode chamar) e "recursos" (dados só leitura).

O Claude foi o primeiro client maior a adotar. A OpenAI adicionou suporte em 2025. Google, Cursor e vários frameworks de agentes (LangChain, LlamaIndex) tem nos roadmaps ou já enviando.

O resultado é constrói uma vez, funciona em todo lugar. A Comuna não mantém uma integração separada por vendor IA — mantemos um servidor MCP, e cada client que suporta MCP pode usar.

Endpoint MCP da Comuna

  • URL do servidor: https://api.comuna.work/mcp
  • Autenticação: OAuth2 (Supabase OAuth Server). A primeira vez que um client conecta, você passa por um fluxo de aprovação e autoriza o client com sua conta da Comuna. Depois, o client recebe um Bearer token que usa pra cada chamada.
  • Versão do protocolo: spec MCP mais recente
  • Espelho REST: as mesmas operações também expostas em https://api.comuna.work/api/v1/* se você precisa de JSON plano sem o framing do MCP.

Catálogo de ferramentas (cerca de 80 ferramentas)

Uma lista não exaustiva do que seu client IA pode chamar:

Boards

list_boards, get_board, create_board, update_board, delete_board

Colunas

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 tarefas

get_my_tasks_today, get_my_tasks_week, get_overdue_tasks

Labels, atribuídos, datas, dependências, checklists, componentes, anexos

~25 ferramentas cobrindo todas as operações em nível de card.

Conhecimento

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 (artefatos HTML interativos)

list_canvases, create_canvas, update_canvas, restore_canvas_version

Coordenação

get_my_context (bootstrap — chame primeiro), report_progress, request_human_review, answer_review, update_coworker_task, get_attention_items

Identidade

register_agent, get_my_agent_identity (pra IA assinar as ações com o próprio avatar)

O schema completo de cada ferramenta (parâmetros de entrada, shape de retorno) está disponível no spec OpenAPI em https://api.comuna.work/openapi.yaml e via discovery MCP padrão (tools/list).

Construindo um client custom

Se você quer conectar a Comuna a algo que não é Claude nem ChatGPT — seu próprio framework de agentes, um CLI, um job CI que atualiza cards automaticamente — aqui o caminho curto:

  1. Dance OAuth: registre seu client no endpoint well-known, leve o usuário pela aprovação, pegue um Bearer token.
  2. Descubra ferramentas: POST /mcp com tools/list pra pegar o catálogo.
  3. Chame ferramentas: POST /mcp com tools/call, passando o nome da ferramenta e argumentos. As respostas incluem o resultado e coaching hints opcionais pro modelo.
  4. Bootstrap: sempre chame get_my_context primeiro em qualquer sessão nova. Retorna as instruções permanentes do usuário, tarefas pendentes e reviews recentes — o estado que a IA precisa pra agir com sentido.
  5. Heartbeat + escala: chame report_progress periodicamente (a cada 30–60s) durante trabalho longo; chame request_human_review antes de qualquer decisão que o humano deveria tomar.

O código do servidor MCP da Comuna está no mesmo repositório que o app, em mcp-server/.

Por que apostamos no MCP

Quando começamos a construir a integração IA da Comuna, consideramos três opções:

  1. SDK LLM nativo por vendor (Anthropic SDK + OpenAI SDK + Google SDK + …). Vendor lock-in por cada um. Schema pra manter por cada um. Ciclo de release por cada um.
  2. Webhook + JSON RPC custom. A gente teria o protocolo; cada client precisaria de um adapter bespoke. O custo cairia no usuário.
  3. MCP (na época novinho, dezembro de 2024).

MCP é a aposta. Um servidor, lista crescente de clients, spec aberto, sem carga de manutenção por vendor. A desvantagem é que alguns clients ainda não têm UIs MCP polidas (Gemini, Cursor). É um custo temporário que aceitamos em troca de não manter três integrações diferentes.

Veja a página do colega IA pro contexto de produto, ou escolha um client pra conectar.

Relacionado

  • Integrações — A Comuna fala com seus clients IA via MCP. Claude e ChatGPT estão conectados hoje; Gemini e Cursor vêm depois. OAuth, sem API keys, sem plugins.
  • Integrações · Claude — Como adicionar o Claude (Anthropic) como colega real nos seus boards da Comuna. OAuth, sem API keys, sem plugins. O plano grátis do Claude serve.
  • Integrações · ChatGPT — Como adicionar o ChatGPT (OpenAI) como colega real nos seus boards da Comuna. OAuth, sem API keys, sem plugins. Requer ChatGPT Plus / Pro.
Experimente a Comuna — grátis para sempre ← Voltar ao início