Skip to main content
MCP and REST share one authority model: the hosted MCP service is a client of the same OrgX authority this documentation describes. This page maps each orgx_* tool to the REST operation that provides the closest public contract, so you can decide per capability whether to integrate over REST directly or through MCP. Three honesty notes up front:
  1. Several MCP tools are compositions — they orchestrate multiple REST calls plus MCP-side logic. Reproducing them over REST means making the same calls yourself.
  2. Some MCP actions have no direct REST equivalent. These are marked MCP-only; use the tool when your integration needs that behavior.
  3. Several REST resources have no MCP tool at all — see the REST-first list.

​
Tool-by-tool mapping

Supporting catalog tools (scaffold_initiative, review_artifact, workspace, and others) follow the same pattern: resource-specific v1 operations are preferred, compatibility entities reads and writes remain for older clients, and scaffold_initiative mirrors POST /api/v1/initiatives.

​
Deprecated memory-tool migration

query_org_memory is deprecated. Use the resource-specific v1 reads and search surfaces described above; keep the old tool only for clients still completing migration.

​
Where REST gives you more than MCP

These resources have no MCP tool — the REST API is the only programmatic surface, and it carries controls MCP does not expose:
  • Work commands — POST /work and POST /work/{taskId}/complete return receipt and ledger-event IDs and accept expected_updated_at / expected_aggregate_version concurrency guards.
  • Operating processes — propose, confirm, activate with expected-version control.
  • Handoffs — the full six-state machine.
  • Discovery runs — evidence-gated workflow discovery and the propose step.
  • Ledger events — cursor replay and the SSE lease.
  • Episodes and projections — derived reads with freshness metadata.
  • Receipt validation and import — including the account-free validator.
  • Run control — POST /api/v1/runs/{runId}/actions/{action} gives API keys pause/resume/cancel/rollback directly.

​
Where MCP gives you more than REST

  • Human-authority flows under the signed-in user (decision resolution, artifact acceptance) without a browser.
  • Run dispatch (orgx_spawn) and run telemetry (activity, attention, questions, execution graphs).
  • Hard delete and the full MCP lifecycle-action vocabulary (orgx_act).
  • Plan sessions, memory search, recommendations, and the free audit.
When a capability appears in both columns, prefer REST for server-to-server integrations — it is the versioned, OpenAPI-described contract — and MCP for AI clients that need tools, approvals, and OAuth.