Skip to content
Orcha Orcha

MCP Server

The Orcha MCP Server is a Model Context Protocol endpoint at /mcp. It lets a coding agent ask “who am I?” and “what should I work on next?”, then act on the answer — creating, updating, and transitioning tickets and editing their Markdown bodies.

Connect over OAuth

Section titled “Connect over OAuth”

Orcha’s MCP server follows the MCP authorization spec: OAuth 2.1, with Orcha as its own authorization server. This is the preferred way to connect — point your client at the endpoint, approve once in the browser, and you’re done:

  1. Set the connector URL to https://api.orcha.run/mcp — no Authorization header.
  2. On first use, the client discovers Orcha’s OAuth endpoints, opens your browser, and you approve on the consent screen.
  3. Orcha issues access and refresh tokens to the client. The client stores them and sends Authorization: Bearer … on every MCP request. You never see, copy, or paste these tokens.

Each approval becomes a connected app in avatar menu → Connected Apps. See OAuth Connect for the full walkthrough, scopes, revocation, and HTTPS requirements.

Self-hosting? Swap https://api.orcha.run/mcp for your domain’s /api/mcp path in every example on this page.

Add to your agent

Section titled “Add to your agent”

Claude Code speaks MCP OAuth. Add Orcha with no Authorization header, then approve from inside a session:

Terminal window
claude mcp add --transport http orcha https://api.orcha.run/mcp

Run /mcp, pick orcha → Authenticate, and approve in the browser. Claude Code discovers Orcha’s OAuth server, registers itself, and stores the tokens Orcha issues, refreshing them automatically. The same /mcp panel shows the connection status.

Prefer a token? When you’d rather not run the browser flow, or you want to commit a project-scoped config your team shares, use the alternative: a Personal Access Token in a .mcp.json at your repo root (team members are prompted to approve it on first use):

{
  "mcpServers": {
    "orcha": {
      "type": "http",
      "url": "https://api.orcha.run/mcp",
      "headers": {
        "Authorization": "Bearer orcha_pat_your_token_here"
      }
    }
  }
}

Every tool is tenant-scoped to the connection’s Role and returns LLM-shaped flat JSON. A read-only connection can call every read tool but is refused on the writes. The connection is refused outright if its credential is missing, malformed, or invalid.

The alternative: Personal Access Token

Section titled “The alternative: Personal Access Token”

When your agent can’t run the OAuth browser flow (Grok, for one), or you’d simply rather hand it a token, mint one in the app from avatar menu → API Tokens and paste it into the agent’s config wherever you see orcha_pat_your_token_here above. It’s also how you authenticate the REST API.

The tools

Section titled “The tools”

Read — orient and understand the work

Section titled “Read — orient and understand the work”
  • whoami — your role, the user and organization you act for, and whether your token is read-only.
  • next_tickets — your work queue in scheduler priority order, each ticket paired with the next workflow state to advance it into.
  • list_tickets — find tickets by project, status, stage, assignee, or search, paginated.
  • get_ticket — a single ticket’s full detail: estimate/ETA, workflow states with three-point estimates, dependency edges, and the Markdown body.
  • get_ticket_body / get_project_body — just the Markdown body and its version (the version a later body write conditions on).
  • list_projects — find projects by search or parent, paginated.
  • get_project — a single project’s detail and its parent/children edges.
  • list_products — the products you can file work against: name, code, description, and their workflows.
  • list_workflows — workflow stage sequences, optionally filtered to one product.
  • get_schedule — your outstanding scheduled work and its ETAs.

Write — act on what it finds

Section titled “Write — act on what it finds”
  • create_ticket / update_ticket — capture a new ticket, or patch an existing one’s fields. create_ticket can fully form a ticket in one call — seed its Markdown body and assign an ownerId alongside the title, sparing follow-up writes — and every ticket it returns carries a direct url you can hand the user to open it.
  • transition_ticket — drive a ticket through its lifecycle: schedule it, start a workflow stage, advance to the next stage, or close / cancel it.
  • update_ticket_body / update_project_body — write the Markdown body with optimistic concurrency: the write conditions on the version you read, and a concurrent edit comes back as a conflict to rebase on — never a silent overwrite.

How it’s served

Section titled “How it’s served”

The MCP server runs inside the Orcha backend and shares the same execution path as the REST API — so the two never disagree about what an operation does. It is stateless Streamable HTTP: there is no session to keep alive, each request carries its own credential.

The full architecture — why the MCP server lives in the backend and reuses the /v1 executor — is in ADR 0008.