orchestra-mcp — a field guide to the Orchestra MCP tools

What the Orchestra MCP tools do, what they quietly do not do, and how to tell which server and whose identity you are holding before you write anything.

Everything here was measured against a running server, not read from documentation.

What this is for

Orchestra fails silently in more ways than it fails loudly: a write returns success with a rejection list buried inside it, a board query returns 128 of 147 tasks with no error, a delete hangs to timeout and then keeps hanging for every delete after it, a thread accepts a reply that no read will ever return. None of that is guessable. This skill is the catalogue.

It is deliberately methodology-free. It answers "why did this call behave that way". It never says which task to take, when a task is done, or how work should be organised — that belongs to whatever runbook you use.

Install

# Global (recommended):
npx skills add ForgePlan/orchestra-mcp -g

# Project-only:
npx skills add ForgePlan/orchestra-mcp

Installs as orchestra-mcp.

What is inside

File	What is in it
SKILL.md	the router — which question goes to which reference
references/failure-modes.md	every way Orchestra fails silently; what is unreachable from MCP; what does not exist in the product
references/query-cookbook.md	filtering, sweeps, cost control, and how to cross-check a count before you report it
references/fields.md	value shapes on read and write, the two-containers trap, field types never to create
references/entities.md	creating, updating, checklists, messages, deleting
references/rendering.md	why written markdown never reads back identical
scripts/orch-verify.sh	deterministic server resolution + write handshake — exit 0 means safe to write
scripts/field-map.sh	dumps the field and option UID map from a running Orchestra

Two servers wear the same name

Orchestra ships two server variants with different tool sets and different identities:

• the desktop app's own endpoint — no auth, acts as the signed-in human, carries navigate_to / get_ui_context;
• an agent endpoint behind a Bearer token — acts as a deployed bot with its own uid, so every write lands under the bot's name, not yours. Carries add_relation / approve_action / switch_workspace / add_members / get_agent_prompt.

A project may legitimately register several at once (different spaces, different rights — a human's session beside a scoped bot). So resolve the server per project, deterministically, not by judgement:

./scripts/orch-verify.sh [role] [--json]

It finds the project's pin file (docs/agents/orchestra.json, with .agents/ and .claude/ as legacy fallbacks), resolves the role to a server, handshakes, and compares the live get_current_context against the pinned workspace and user.

Exit	Meaning
0	resolved, workspace and user MATCH — safe to write
65	MISMATCH — the server answers as a different space/user; do not write
66	no pin file (then: exactly one connected Orchestra server may be used; several — ask)
69	unreachable / handshake failed
75	reachable but NOT READY — its workspace data is still loading and every tool refuses
78	config invalid, role missing, or the token env var is not set

The pin file never holds a token — only the name of the environment variable that does.

Tool names are written bare

query_entities, never a prefixed form. The prefix is unstable twice over: the runtime spelling differs (Claude Code puts two underscores between server and tool, others use one), and the server segment is whatever the project's own MCP config registered. orch-verify.sh prints the correct prefix for your runtime as toolPrefixHint.

Source of truth

Kept in sync from the orchestra-mcp skill in ForgePlan/marketplace. File issues and improvements against the marketplace.

Not affiliated with Orchestra. This is an independent field guide written from measurement.