MCP & AI agents

Orkestra exposes an MCP server covering nearly all of the backend with one tool per domain. claude.ai and ChatGPT connect with OAuth 2.1 by pasting a single URL — no tokens to copy. Any other compatible MCP client can operate Orkestra in natural language.

For claude.ai and ChatGPT you don’t copy any token: they connect with OAuth 2.1 by pasting the URL https://mcp.orkestra.team/mcp.

  • claude.ai — Settings → Connectors → Add custom connector → paste the URL → log in and accept the consent screen in Orkestra.
  • ChatGPT — connectors in developer mode, same URL.
  • Claude Code (terminal) — claude mcp add --transport http orkestra https://mcp.orkestra.team/mcp (OAuth opens in the browser).

Reconnections are silent: once approved, you’re never asked to consent again. The in-app interactive guide lives at Connect your AI.

Supported transports

The Orkestra MCP server supports two transports:

  • Streamable HTTP (remote) — the client connects to https://mcp.orkestra.team/mcp. This is the path for claude.ai, ChatGPT and Claude Code (OAuth), and also serves custom HTTP clients (N8N, scripts) via the Authorization: Bearer ork_... header.
  • STDIO (local) — the client starts the server as a subprocess. Useful for Claude Desktop, where the MCP runs alongside the client. Auth via MCP_TOKEN env var.

Generate an MCP token

Tokens still exist for local STDIO clients or custom HTTP clients (N8N, scripts, your own agent). Go to Settings → MCP Tokens → Create token. Give it a descriptive name (e.g. “Claude Desktop Juan’s laptop”) and choose the access level: full or read-only (a read-only token can call only read tools).

The token value is shown only once. Copy it and store it in a password manager. If you lose it, create a new one (and revoke the old). Revoking a token also disconnects the associated OAuth clients.

Available tools

Instead of one tool per action, Orkestra exposes one tool per domain. Each takes an action parameter that unlocks that domain’s actions, and action: "describe" returns the full schema of an action only when the agent needs it. This keeps the tool list small. Some domains:

  • orkestra_tasks, orkestra_projects, orkestra_wiki — tasks, projects and docs
  • orkestra_organizations, orkestra_areas — organizations, areas and org chart
  • orkestra_sprints, orkestra_time, orkestra_planning — cycles, time tracking and planning
  • orkestra_analytics, orkestra_finance, orkestra_stock — analytics & reports, finance, inventory
  • products and goals; admin (roles, audit, automation); integrations; templates
  • check-ins; helpdesk; client portal; bulk operations
  • user and activities; custom fields; chat; notifications; data tables; OrgOS
  • plus the discrete tools orkestra_overview (what Orkestra is, how the domains chain and your organizations: the first call an agent makes in a conversation with no context), orkestra_search, orkestra_help and the confirm tool (orkestra_confirm_action)

Every fact in its record

Agents like to “note things down”: ask that the bathroom task needs three boxes of screws and watch it write a comment. That comment is text nobody totals, buys or consumes. So the server refuses prose where a record exists: a comment, a description or a chat message that reads like a supply with a quantity, money, hours worked, a decision, a dependency, a deadline, an owner or a status is rejected, and the reply names the action that records it (request_stock, create_expense, log_time, capture_decision, assign_task…). If it really is prose about the topic and not the fact itself, the agent repeats the call with prose_intended: true and the text is written as given.

When reading a task the agent also receives the facts its description or comments already carry as text, with the action that records each, so it can offer to move them where they belong. Settings → Connect AI shows how many times your AI insisted with prose_intended: worth checking where that landed.

User AI context

Every user can fill in a free-text field (up to 2000 chars) in their profile (Settings → AI context) describing their role, expertise, communication preferences, timezone, etc. The MCP exposes it two ways so agents consume it without you repeating yourself each session:

  • Action orkestra_user → get_profile — returns the aboutMe field wrapped in <user_context>...</user_context> with an explicit instruction to the agent to treat the content as data, not instructions (prompt-injection defense).
  • Resource orkestra://user/context — an MCP resource the client lists for you to attach to a conversation, injecting the context into the agent’s system prompt.

Resources and prompts

Beyond the user context, the server exposes resources. No current connector reads them on its own: claude.ai, ChatGPT and Claude Code list them for you to attach by hand when you want them in context.

  • orkestra://user/myday — overdue and upcoming assigned tasks + scheduled activities.
  • orkestra://user/organizations — org and project map with their IDs.
  • orkestra://user/context — the user’s AI context (aboutMe).
  • orkestra://org/{orgId}/world-model — OrgOS: DRIs, decisions and gaps.
  • orkestra://org/{orgId}/structure — areas and org chart.

The server also ships 5 ready-made prompts that compatible clients surface as commands. Their titles are Spanish in every client — prompts, like tool descriptions, are registered once per process and cannot vary per user: Resumen semanal (weekly summary), Planificar un ciclo (plan a cycle), Triaje de pendientes (pending triage), Mi día (my day) and Reporte de estado de proyecto (project status report).

Automatic preview / confirm

All write operations go through a preview/confirm flow. When an agent requests to create, update or delete something, the response is a preview with an actionId. Only when the agent calls the orkestra_confirm_action tool with that actionId is the operation executed.

In STDIO clients that support MCP elicitation (Claude Desktop, Claude Code) the confirmation appears as a native dialog instead of the two-step flow. This prevents an agent from executing destructive changes by accident or hallucination. Limit: 30 confirmations per minute per user.

Real-time

Changes made via MCP propagate live: the web app updates over Socket.io, and webhooks, the Slack integration and automation rules fire just as if the change came from the app (Redis event bridge).

Connecting clients

For step-by-step guides with copy-paste configuration, go to the full AI Agents page. It covers the OAuth connection for claude.ai and ChatGPT, Claude Code, and local/custom clients with a token.

Limits and rate limiting

The MCP server respects the same rate limits as the REST API: 1000 requests per minute per token on normal operations, 100/minute on sensitive write operations (bulk, custom roles, webhooks), and 30 confirmations per minute per user. If you see 429, wait and retry with exponential backoff.

What’s NOT in MCP (by design)

Some operations are intentionally excluded from MCP:

  • MCP token management — avoid circular loops (a token can’t create tokens).
  • Calendar sync OAuth — requires user redirection.
  • Export/Import with files — the MCP transport doesn’t handle large binaries well.

Resources