MCP & AI agents

Orkestra exposes a native MCP server covering 99% of the backend with 29 domain tools (~296 actions). claude.ai and ChatGPT connect via OAuth 2.1 by pasting a single URL — no tokens to copy. Any other compatible MCP client can operate Orkestra with natural language.

Connect with OAuth (recommended)

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 29 domain tools. Each takes an action parameter that unlocks the ~296 backend actions, and action: "describe" returns the full schema of an action only when the agent needs it. This keeps the tool list small (up to 4× less client context than one tool per action). Some domains:

  • orkestra_tasks, orkestra_projects, orkestra_wiki — tasks, projects and wiki
  • orkestra_organizations, orkestra_areas — organizations, areas and org chart
  • orkestra_sprints, orkestra_time, orkestra_planning — sprints, time tracking and planning
  • orkestra_analytics, orkestra_finance, orkestra_stock — analytics & reports, finance, inventory
  • products, portfolio and goals; admin (RBAC, audit, automation); integrations; templates
  • processes and check-ins; helpdesk; client portal; bulk operations
  • user and activities; custom fields; AI workflows; chat; notifications; data tables; OrgOS
  • plus discrete search and confirm tools (orkestra_confirm_action)

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 that compatible clients (Claude Desktop, among others) can auto-load when starting a session, injecting the context into the agent's system prompt.

Resources and prompts

Beyond the user context, the server exposes resources that compatible clients can auto-load:

  • 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: Weekly summary, Plan sprint, Backlog triage, My day and 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