Path: /docs/mcp

Orchestrator exposes a Model Context Protocol HTTP surface so Cursor and other clients can call tools with a Bearer API token. Production is cloud-based at getorchestrator.app. Humans use the board and workflows UI. Agents use MCP.

Source of truth for tool names: src/lib/mcp/registry.ts.

Authentication (required)

Surface	How you authenticate
Web app	NextAuth (GitHub OAuth and optional email/password). Session cookie (__Secure-authjs.session-token on HTTPS).
MCP / CLI	Bearer personal access token only. Cookies are ignored when Authorization: Bearer … is present.

MCP does not use browser cookies. Create a token while signed in, copy it once, put it in Cursor headers.

Create and revoke API tokens

1. Sign in at https://getorchestrator.app/login
2. Open API Tokens: /admin/org/api-tokens (also under Tools → CLI → API Tokens)
3. Create a token. The raw orc_… secret is shown once. Store it in a password manager or local env (ORC_TOKEN).
4. Revoke from the same page (sets isActive: false). Revoked tokens are rejected immediately (cache invalidated).

Tokens are stored as SHA-256 hashes (tokenHash). The raw secret is never listed again after create. Legacy plaintext rows are accepted once, then backfilled to hashed storage.

Cloud first

Base	https://getorchestrator.app
Health	GET /api/mcp/health (public)
Tools	GET /api/mcp/tools (Bearer required in production)
Call	POST /api/mcp (Streamable HTTP) or POST /api/mcp/call (JSON-RPC helper)

Cloud-safe tools read and write Hostinger Postgres (same board as the web UI). They do not need a git checkout on the server.

Prefer: ticket.list, board.get, workflow.get, ticket.create, ticket.update, orchestrator.project.list.

Local-only (not cloud-safe): ticket.sync, git_*, path-based project.create / project.connect, workflow.ticket-to-pr and related PR helpers.

Cursor configuration (verified shape)

Working Cursor MCP config for production (Streamable / HTTP URL + Bearer header). Replace the token. Do not commit real secrets.

json
{
  "mcpServers": {
    "orchestrator": {
      "url": "https://getorchestrator.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ORCHESTRATOR_API_TOKEN"
      }
    }
  }
}

Notes:

• Some Cursor builds also accept "transport": "http" with the same url / headers.
• Local debugging may point at http://127.0.0.1:7001/api/mcp or /api/mcp/call with the same Bearer header.
• On 401, fix or recreate the token. Do not fall back to email/password inside the agent loop.

Health (example)

bash
curl -sS https://getorchestrator.app/api/mcp/health

Verified production shape includes:

json
{
  "status": "ok",
  "service": "orchestrator-mcp",
  "mode": "cloud",
  "baseUrl": "https://getorchestrator.app",
  "docs": "https://getorchestrator.app/docs/mcp",
  "cloudPreferredTools": [
    "ticket.list",
    "board.get",
    "workflow.get",
    "ticket.create",
    "ticket.update",
    "orchestrator.project.list"
  ]
}

List tools

bash
curl -sS https://getorchestrator.app/api/mcp/tools \
  -H "Authorization: Bearer YOUR_API_TOKEN"

• Missing / invalid token → 401
• Each tool includes cloudSafe: true|false

Core cloud tools

Tool	Purpose
orchestrator.project.list	Projects visible to the token owner
ticket.list	List tickets. Requires projectCode.
board.get	Kanban columns + cards from Postgres
workflow.get	Status graph + automation rules
ticket.create	Create ticket (idempotent by existing number / ticketKey / externalKey)
ticket.update	Update by id / key / externalKey
orchestrator.ticket.get	Read one ticket

board.get

json
{ "projectCode": "BLAH", "limitPerColumn": 40 }

Same Postgres board as /projects/BLAH/board. Unauthorized projectCode fails.

Idempotent ticket.create

Pass ticketKey or externalKey. If a matching ticket exists (by number, key, or externalKey), MCP returns that ticket with existing: true instead of creating a duplicate.

Troubleshooting

Symptom	Check
401 on tools/call	Token missing, mistyped, expired, or revoked. Recreate under /admin/org/api-tokens.
Project not found	Token user’s orgs do not include that projectCode. Call orchestrator.project.list.
git_* / ticket.sync fails on cloud	Expected. Those need a local checkout. Use board/ticket tools instead.
Web /projects redirects to /login	Expected when signed out. Sign in with GitHub (or email if enabled).

Related

• Board
• Workflows
• API Reference
• Getting Started
• Rule: .orchestrator/agents/.cursor/rules/auth-orchestrator/RULE.md