Comuna · Integrazioni · MCP

Un server, qualsiasi client MCP

Comuna espone i suoi dati e operazioni come server Model Context Protocol. Claude e ChatGPT lo usano attraverso i loro UI nativi; qualsiasi altro client MCP-capable (agente custom, framework, script) può usare lo stesso endpoint.

Cos'è MCP

Il Model Context Protocol (MCP) è uno standard aperto pubblicato da Anthropic a fine 2024 per connettere modelli IA con strumenti e fonti di dati. È basato su HTTP, usa OAuth per l'auth, ed espone capability come catalogo scopribile di "strumenti" (funzioni che il modello può chiamare) e "risorse" (dati di sola lettura).

Claude è stato il primo client maggiore ad adottarlo. OpenAI ha aggiunto il supporto nel 2025. Google, Cursor e diversi framework di agenti (LangChain, LlamaIndex) lo hanno nelle roadmap o già spediscono.

Il risultato è costruisci una volta, funziona ovunque. Comuna non mantiene un'integrazione separata per vendor IA — manteniamo un server MCP, e ogni client che supporta MCP può usarlo.

Endpoint MCP di Comuna

  • URL del server: https://api.comuna.work/mcp
  • Autenticazione: OAuth2 (Supabase OAuth Server). La prima volta che un client si connette, passi per un flusso di approvazione e autorizzi il client con il tuo account Comuna. Dopo, il client riceve un Bearer token che usa per ogni chiamata.
  • Versione del protocollo: spec MCP più recente
  • Mirror REST: le stesse operazioni esposte anche a https://api.comuna.work/api/v1/* se ti serve JSON piatto senza il framing MCP.

Catalogo strumenti (circa 80 strumenti)

Una lista non esaustiva di ciò che il tuo client IA può chiamare:

Board

list_boards, get_board, create_board, update_board, delete_board

Colonne

create_column, update_column, delete_column

Card

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

Query di task

get_my_tasks_today, get_my_tasks_week, get_overdue_tasks

Label, assegnati, date, dipendenze, checklist, componenti, allegati

~25 strumenti che coprono tutte le operazioni a livello card.

Conoscenza

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

Chat & DM

list_channels, get_channel_messages, send_message, start_dm, send_dm

Canvas (artefatti HTML interattivi)

list_canvases, create_canvas, update_canvas, restore_canvas_version

Coordinamento

get_my_context (bootstrap — chiama per primo), report_progress, request_human_review, answer_review, update_coworker_task, get_attention_items

Identità

register_agent, get_my_agent_identity (così l'IA firma le sue azioni col proprio avatar)

Lo schema completo di ogni strumento (parametri di input, shape di ritorno) è disponibile nello spec OpenAPI a https://api.comuna.work/openapi.yaml e via discovery MCP standard (tools/list).

Costruire un client custom

Se vuoi connettere Comuna a qualcosa che non è Claude o ChatGPT — il tuo framework di agenti, un CLI, un job CI che aggiorna card automaticamente — ecco il percorso breve:

  1. Dance OAuth: registra il tuo client all'endpoint well-known, fai passare l'utente per l'approvazione, ottieni un Bearer token.
  2. Scopri strumenti: POST /mcp con tools/list per ottenere il catalogo.
  3. Chiama strumenti: POST /mcp con tools/call, passando nome dello strumento e argomenti. Le risposte includono il risultato e coaching hint opzionali per il modello.
  4. Bootstrap: chiama sempre get_my_context per primo in ogni nuova sessione. Restituisce le istruzioni permanenti dell'utente, task pendenti e review recenti — lo stato che l'IA serve per agire sensatamente.
  5. Heartbeat + escala: chiama report_progress periodicamente (ogni 30–60s) durante lavoro lungo; chiama request_human_review prima di qualsiasi decisione che l'umano dovrebbe prendere.

Il codice del server MCP di Comuna è nello stesso repository dell'app, sotto mcp-server/.

Perché abbiamo scommesso su MCP

Quando abbiamo iniziato a costruire l'integrazione IA di Comuna, abbiamo considerato tre opzioni:

  1. SDK LLM nativo per vendor (Anthropic SDK + OpenAI SDK + Google SDK + …). Vendor lock-in per ognuno. Schema da mantenere per ognuno. Ciclo di release per ognuno.
  2. Webhook + JSON RPC custom. Avremmo posseduto il protocollo; ogni client avrebbe bisogno di un adapter bespoke. Il costo sarebbe ricaduto sull'utente.
  3. MCP (allora nuovissimo, dicembre 2024).

MCP è la scommessa. Un server, lista crescente di client, spec aperta, nessun carico di manutenzione per vendor. Lo svantaggio è che alcuni client non hanno ancora UI MCP raffinate (Gemini, Cursor). È un costo temporaneo che abbiamo accettato in cambio di non mantenere tre integrazioni diverse.

Vedi la pagina del collega IA per il contesto prodotto, o scegli un client da connettere.

Correlato

  • Integrazioni — Comuna parla con i tuoi client IA via MCP. Claude e ChatGPT sono connessi oggi; Gemini e Cursor seguono. OAuth, niente API key, niente plugin.
  • Integrazioni · Claude — Come aggiungere Claude (Anthropic) come vero collega sui tuoi board Comuna. OAuth, niente API key, niente plugin. Il piano gratuito di Claude va bene.
  • Integrazioni · ChatGPT — Come aggiungere ChatGPT (OpenAI) come collega reale sui tuoi board Comuna. OAuth, niente API key, niente plugin. Richiede ChatGPT Plus / Pro.
Prova Comuna — gratis per sempre ← Torna alla home