Comuna · Integrations · MCP

One server, any MCP client

Comuna exposes its data and operations as a Model Context Protocol server. Claude and ChatGPT use it through their native UIs; any other MCP-capable client (custom agent, framework, script) can use the same endpoint.

What MCP is

The Model Context Protocol (MCP) is an open standard published by Anthropic in late 2024 for connecting AI models to tools and data sources. It's HTTP-based, uses OAuth for auth, and exposes capabilities as a discoverable catalogue of "tools" (functions the model can call) and "resources" (read-only data).

Claude was the first major client to adopt it. OpenAI added support in 2025. Google, Cursor, and several agent frameworks (LangChain, LlamaIndex) have it on their roadmaps or already shipping.

The result is build once, work everywhere. Comuna doesn't maintain a separate integration per AI vendor — we maintain one MCP server, and every client that supports MCP can use it.

Comuna's MCP endpoint

  • Server URL: https://api.comuna.work/mcp
  • Authentication: OAuth2 (Supabase OAuth Server). The first time a client connects, you go through an approval flow and authorize the client with your Comuna account. After that, the client gets a Bearer token it uses for every call.
  • Protocol version: latest MCP spec
  • REST mirror: same operations also exposed at https://api.comuna.work/api/v1/* if you need plain JSON without the MCP framing.

Tool catalogue (about 80 tools)

A non-exhaustive list of what your AI client can call:

Boards

list_boards, get_board, create_board, update_board, delete_board

Columns

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

Task queries

get_my_tasks_today, get_my_tasks_week, get_overdue_tasks

Labels, assignees, dates, dependencies, checklists, components, attachments

~25 tools covering all card-level operations.

Knowledge

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 (interactive HTML artifacts)

list_canvases, create_canvas, update_canvas, restore_canvas_version

Coordination

get_my_context (bootstrap — call first), report_progress, request_human_review, answer_review, update_coworker_task, get_attention_items

Identity

register_agent, get_my_agent_identity (so the AI signs its actions with its own avatar)

The full schema for each tool (input parameters, return shape) is available in the OpenAPI spec at https://api.comuna.work/openapi.yaml and via standard MCP discovery (tools/list).

Building a custom client

If you want to wire Comuna to something that isn't Claude or ChatGPT — your own agent framework, a CLI, a CI job that updates cards automatically — here's the short path:

  1. OAuth dance: register your client at the well-known endpoint, walk the user through approval, get a Bearer token.
  2. Discover tools: POST /mcp with tools/list to get the catalogue.
  3. Call tools: POST /mcp with tools/call, passing the tool name and arguments. Responses include the result and optional coaching hints for the model.
  4. Bootstrap: always call get_my_context first in any new session. It returns the user's standing instructions, pending tasks, and recent reviews — the state the AI needs to act sensibly.
  5. Heartbeat + escalate: call report_progress periodically (every 30–60s) during long work; call request_human_review before any decision the human should make.

Comuna's MCP server source is in the same repository as the app, under mcp-server/.

Why we bet on MCP

When we started building Comuna's AI integration, we considered three options:

  1. Native LLM SDK per vendor (Anthropic SDK + OpenAI SDK + Google SDK + …). Each vendor lock-in. Each schema to maintain. Each release cycle to track.
  2. Webhook + custom JSON RPC. We'd own the protocol; every client would need a bespoke adapter. The cost would fall on the user.
  3. MCP (then brand new, December 2024).

MCP is the bet. One server, growing client list, open spec, no per-vendor maintenance burden. The downside is that some clients still don't have polished MCP UIs (Gemini, Cursor). That's a temporary cost we accepted in exchange for not maintaining three different integrations.

See the AI coworker page for the product context, or pick a client to connect.

Related

  • Integrations — Comuna talks to your AI clients via MCP. Claude and ChatGPT are wired in today; Gemini and Cursor are next. OAuth, no API keys, no plugins.
  • Integrations · Claude — How to add Claude (Anthropic) as a real coworker on your Comuna boards. OAuth, no API keys, no plugins. Free Claude plan works.
  • Integrations · ChatGPT — How to add ChatGPT (OpenAI) as a real coworker on your Comuna boards. OAuth, no API keys, no plugins. Requires ChatGPT Plus / Pro.
Try Comuna — free forever ← Back to home