> ## Documentation Index > Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP and REST parity > Every orgx_* MCP tool mapped to the REST route(s) it calls — and an honest list of what each surface has that the other does not. 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](#where-rest-gives-you-more-than-mcp). ## Tool-by-tool mapping | MCP tool | What it does | REST route(s) behind it | Direct REST parity? | | --------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `orgx_bootstrap` | Session context, scopes, tool routing | `GET /api/v1/me`, MCP session context | Partial — credential identity is public REST; the routing map is MCP-side | | `orgx_search` | Find entities, decisions, artifacts, memory | Resource-specific v1 reads; compatibility entities read for legacy types | Typed v1 searches: direct parity. Broad relevance search: MCP-only | | `orgx_inspect` | Hydrate one entity with execution context | Resource-specific v1 read + MCP execution context | Partial — the resource read is REST; the context pack is MCP-only | | `orgx_write` | Create or update one record | Resource-specific v1 write; compatibility entities write for legacy types | Direct parity where a v1 resource exists | | `orgx_attach` | Attach an artifact or proof URL | MCP artifact attachment action | Use `POST /api/v1/artifacts` — same registration, public contract | | `orgx_act` | Lifecycle actions (launch, complete, block, delete, ...) | MCP lifecycle actions | Partial — use `PATCH /api/entities` status writes, `POST /api/v1/lifecycle`, and run action routes; hard `delete` has no API-key equivalent | | `orgx_plan` | Tracked plan sessions (start/improve/edit/complete) | MCP plan-session actions | MCP-only | | `orgx_spawn` | Guard, classify, and dispatch agent work | MCP execution controls (`POST /api/v1/spawn` is the public gate-check) | MCP-only for actual dispatch; the pre-flight gate check is public REST | | `orgx_decide` | Create, list, approve, reject decisions | Create/read: `POST`/`GET /api/v1/decisions`; resolution: MCP decision actions | Create/read: direct parity. Resolution: human-session authority by design | | `orgx_submit_receipt` | Submit flywheel receipts | MCP receipt submission action | MCP-only; the portable [agent-work-receipt import](/docs/api/entities/receipt) is the public REST proof path | | `orgx_emit_activity` | Run telemetry | MCP live-activity action | MCP-only | | `orgx_request_attention` | Typed human-interruption request | MCP live-attention action | MCP-only | | `orgx_poll_attention` | Read the owner's response | MCP live-attention read | MCP-only | | `orgx_ack_attention` | Report continuation state | MCP live-attention acknowledgement | MCP-only | | `orgx_request_question` | Forward a checkpoint question | MCP live-questions action | MCP-only | | `orgx_poll_question` | Read the durable answer | MCP live-questions read | MCP-only | | `orgx_emit_execution_graph` | Emit execution graph + trust ledger | MCP execution-graph action | MCP-only | | `orgx_apply_changeset` | Idempotent transactional changeset | MCP changeset action | MCP-only | | `orgx_recommend` | Next-step and morning-brief reads | MCP chronicle and recommendation actions | MCP-only | | `orgx_free_audit` | Autonomy benchmark scores | MCP reads plus server-side scoring | MCP-only | 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`](/docs/api/entities/initiative). ### 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](/docs/api/entities/work-item)** — `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](/docs/api/entities/operating-process)** — propose, confirm, activate with expected-version control. * **[Handoffs](/docs/api/entities/handoff)** — the full six-state machine. * **[Discovery runs](/docs/api/entities/discovery-run)** — evidence-gated workflow discovery and the propose step. * **[Ledger events](/docs/api/entities/ledger-event)** — cursor replay and the SSE lease. * **[Episodes](/docs/api/entities/episode)** and **[projections](/docs/api/entities/projections)** — derived reads with freshness metadata. * **[Receipt validation and import](/docs/api/entities/receipt)** — 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.