---
title: MCP reference
---

Loom serves its operations as MCP tools at `<loom>/mcp`. Any MCP client that
speaks streamable HTTP connects with a URL and a bearer token. The tool list
is generated from the same operation registry as the [HTTP API](/ko/reference/http-api),
and a tool call runs the same authorization, rate limit, audit and idempotency
path as `POST /v1/<op>`. The transport is `server/transport/mcp.py`, with a
tool call in `mcp_call.py` and `mcp_outcome.py`, bearer checks in `mcp_auth.py`, its
listing in `mcp_tools.py`, schema shaping in `mcp_schemas.py`, protocol and
session constants in `mcp_config.py` and the curated descriptions in
`mcp_descriptions.py`.

Wiring a specific client (Claude Code, Codex, Cursor, VS Code, Claude Desktop
and others) with `loom install` or by hand is in
[MCP clients](/ko/features/integrations/mcp-clients).

## Endpoint

| Request                          | Does                                                                                                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /mcp`                      | One JSON-RPC request or a batch of 1 to 64. The answer is a JSON body, not an event stream. A notification answers `202` with no body.                              |
| `DELETE /mcp` + `Mcp-Session-Id` | Ends the session and closes its implicit run. Rate-limited as `run.complete`, per caller within the org's budget: past the cap it answers `429` with `Retry-After`. |

Query parameters on the URL select what `tools/list` shows for that connection:

- `?toolset=` picks the roster that is listed ([Toolsets](#toolsets)). Default:
  `LOOM_MCP_TOOLSET` (`core`).
- `?schema_profile=` picks the listing's shape: `standard` (the curated
  description and the input schema; the default, `LOOM_MCP_SCHEMA_PROFILE`),
  `full` (adds `outputSchema`) or `compact` (the first paragraph and the
  argument tree).

An unknown value for either falls back to the deployment default, so a typo
never widens or narrows a listing silently. The `?toolset=` value also shapes the
session primer (`initialize` instructions, `server/discover`, the `loom` prompt,
`loom://primer` and `loom_activate`): the primer names an op's own tool when the
toolset lists it, else the op name marked "(via loom_op)", and leaves out an op
`loom_op` does not route there.

Methods served: `initialize`, `notifications/initialized`,
`notifications/cancelled`, `ping`, `tools/list`, `tools/call`, `prompts/list`,
`prompts/get` (the `loom` prompt: the session primer), `resources/list`,
`resources/read` (`loom://primer`) and `server/discover`. List results carry
`ttlMs` and `cacheScope` hints so a client can cache them.

**Protocol versions.** `2025-11-25`, `2025-06-18`, `2025-03-26` and
`2024-11-05` (`MCP_SUPPORTED_PROTOCOL_VERSIONS`). `initialize` answers with the
client's version when it is one of these, else `2025-11-25`. An
`MCP-Protocol-Version` header naming another revision is HTTP 400 with JSON-RPC
error `-32022`, whose `data.supported` lists the served ones. `server/discover`
answers with the same list, the capabilities, the server identity and the
instructions.

## Authentication

`LOOM_MCP_AUTH_MODE` decides which methods need a bearer:

| Mode                 | Bearer required on                                                             |
| -------------------- | ------------------------------------------------------------------------------ |
| `required` (default) | every method except notifications                                              |
| `discovery_only`     | `tools/call` only; every other method is open                                  |
| `open`               | nothing; a cryptographically invalid bearer is ignored (trusted networks only) |

A server on a non-loopback `LOOM_BIND_HOST` refuses to start with `open` unless
`LOOM_ALLOW_INSECURE=1`. A deployment with auth off (`LOOM_AUTH_REQUIRED=false`)
behaves as `open`. A missing or invalid bearer on a gated method is HTTP `401` with
`WWW-Authenticate: Bearer realm="loom"` (plus `error="invalid_token"` when a
token was sent). A token that cannot be checked yet, because the revocation
list has not loaded, is HTTP `503` with `Retry-After` instead, so the client
keeps the token and retries. **Why a 401 and not a JSON-RPC error:** clients key their
"needs authentication" flow, and their OAuth discovery, on the HTTP status; a
JSON-RPC error body would surface as a parse or tool error instead. The token
is an ordinary Loom JWT; see [Tokens and grants](/ko/guides/tokens-and-grants).

The bearer is read from the `Authorization` header only. A token passed as `?token=` on
the `/mcp` URL is ignored and the request is unauthenticated: request lines land in proxy
and access logs, where a URL token would be written in the clear.

A bearer that verifies but fails required cell provisioning is refused in every mode;
an unavailable provisioning read answers retryable 503. Neither becomes an anonymous
caller. See [cell provisioning](/ko/architecture/cells#scim-and-sign-in-across-cells).

### OAuth

Served only with `LOOM_OAUTH_ENABLED=true`. Loom is an OAuth 2.1 authorization server for clients that
connect by browser sign-in instead of a pasted token (`server/auth/oauth.py`):

- Discovery at `/.well-known/oauth-authorization-server` and
  `/.well-known/oauth-protected-resource`.
- Dynamic client registration at `/oauth/register`: public clients, PKCE
  `S256` required.
- `/oauth/authorize` and `/oauth/token` issue an access token plus a rotating
  refresh token. A refresh succeeds only when the request names the
  `client_id` the token was issued to.
- The access token is a Loom JWT for the signed-in user, so namespaces the user
  joins later are reachable on the same connection.
- Sign-in uses Loom's password login unless `LOOM_OAUTH_LOGIN_PROVIDER=oidc`
  delegates it to an external identity provider (`LOOM_OIDC_ISSUER`,
  `LOOM_OIDC_CLIENT_ID`, `LOOM_OIDC_CLIENT_SECRET`). Delegating sign-in also
  closes password self-signup.
- A remote deployment must serve HTTPS and set `LOOM_OAUTH_ISSUER` to its
  public `https://` base URL.
- A registered redirect URI must be absolute and fragment-free: `https`, `http`
  to a loopback host, or an app scheme (`cursor://…`). The sign-in page names
  the host the authorization goes to.
- Each refresh re-checks that the account is still active and re-derives its
  roles, so a released account, or a subject removed from
  `LOOM_PLATFORM_ADMINS`, does not keep its access by refreshing.

[Security](/ko/architecture/security) covers the token model behind this.

## Sessions and identity

- **Session id.** `initialize` assigns an `Mcp-Session-Id` and every response
  echoes it. The client's `clientInfo.name` is cached against it and becomes the
  `agent` of later calls, slugified (`Cursor` → `cursor`; absent →
  `claude-desktop`). The cache is in-process and bounded.
- **Identity defaults.** Tool calls usually carry only the action's arguments. The
  server fills `org` from the token and `namespace` and `agent` from the caller's
  default workspace; explicit arguments win. `code.*` calls resolve to the code plane
  instead, and on the `assistant` toolset a read that names no `namespace` or no `agent`
  follows that toolset's rules (see [The assistant toolset](#the-assistant-toolset)). An `org`
  argument the token may not act in is refused (`ORG_MISMATCH`): a token acts in its
  own org, an org-wide (`*`) token or a platform admin in any org, the same rule as
  over HTTP (`authz.may_act_in_org`). A restricted namespace still refuses every other
  org, platform admins included. `loom_search` takes no `namespace` argument: it
  searches the caller's home namespace and its other memory-kind namespaces, up to the
  fan-out cap.
- **Code scope.** A client may send `X-Loom-Code-Scope: <org>/<namespace>` (the
  Claude Code plugin sends the repository its checkout resolved to). It applies
  to every `code.*` call that names no namespace, and authorization then runs on
  that namespace as if it had been named. `loom_search` under the header also reads
  the repository's documents and `decision` memories from its trunk code namespace,
  when the caller may read it, and runs the tracker duplicate check for a
  defect-shaped query. A `memory.set` with no `repo:` tag takes the `repo:<id>` of the
  repository configured for the scope's namespace, when the scope's org is the write's
  org and the caller may read that repository; with such a scope, a write into another
  configured code namespace takes that namespace's repository tag instead. A scope that
  names no configured, readable repository adds no tag, and an explicit `repo:` tag
  always stays.
- **Implicit run.** One run per (org, token subject, session), begun in the
  run ledger by the session's first run-scoped tool call and filed in the
  caller's default namespace; writes carry its `run_id` (except `run.*`, which
  names its own run, `code.*`, which acts as the deployment's code identity, and
  `working_memory.*` and `conversation.update`, where `run_id` scopes or binds the
  row), and reads are labelled with it but not filtered. The run closes on
  `DELETE /mcp`, or when the `mcp_session_run_sweep` worker finds no call of the
  token under it for `LOOM_MCP_SESSION_RUN_IDLE_SECONDS` (default 1800); a
  deployment that runs no background workers anywhere keeps idle runs open. The
  run stores no call count: its calls are the `agent_events` rows with its
  `run_id`. See [Runs](/ko/features/runs).

## Tool list

Every registry operation not in `_MCP_HIDDEN_OPS` is a tool:

- **Name.** `loom_` plus the op name with dots as underscores (`memory.set` →
  `loom_memory_set`).
- **Description.** The curated text in `TOOL_DESCRIPTIONS`
  (`server/transport/mcp_descriptions.py`) when there is one, else a one-line
  fallback with the op's latency budget, idempotency and minimum role. The
  curated texts say when to use a tool and when not to; the choice is left to
  the model. A text names other ops by op name, and each listing renders it for
  the client that reads it (`name_ops_for_listing` in
  `server/transport/mcp_op.py`): an op the listing carries is named by its
  tool (`loom_memory_update`), and an op it does not carry keeps its op name,
  the one `loom_op` takes, with "(via loom_op)" after its first mention when
  `loom_op` routes it on that connection; it does not route a hidden op, a
  write on `readonly` or anything on `assistant`. Input field descriptions, and
  the output schema the `full` profile keeps, are rendered the same way, and so
  is a hidden op's `instead` text; `loom_op`'s own text, which is about op
  names, is built per listing instead. Mentor text is rendered for the
  caller's listing over MCP too (a tool result's `hint`, `context.pack`'s
  `mentor` section, and `mentor.brief`'s hints and plane `when`); over HTTP it
  reads as stored.
- **Input schema.** The op's Pydantic input model without the fields the
  server fills itself (`org`, `agent`, `user_id`, `session_id`, `consumer`),
  the dashboard-only fields (`_HIDDEN_OP_PROPS` in
  `server/transport/mcp_schemas.py`) and every field marked `MCP_HIDDEN`;
  `namespace` stays as an optional property. Hidden fields stay accepted by
  name.
- **Annotations.** `readOnlyHint`, `destructiveHint` and `idempotentHint` are
  derived from the registry (role, idempotency, audit, destructive verbs in the
  name). `readOnlyHint` is true only for an idempotent viewer op that is
  neither audited nor marked `writes`, so a client that auto-approves read-only
  tools never runs a state change unprompted. They are hints; the role check at
  call time is the boundary.

Three synthetic tools are listed on every toolset but `assistant`:

| Tool            | Does                                                                                                                                                                                                                 |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loom_search`   | One call searches memory, profile, knowledge and conversations in parallel and returns all four sections. `explain: true` adds why each memory hit ranked.                                                           |
| `loom_activate` | Returns the session primer (profile, preferences, default workspace), the same text as the `loom` prompt.                                                                                                            |
| `loom_op`       | `{op, arguments}` runs any op the roster does not list, through the same path as a listed tool; `{op: "help", query}` lists up to 15 matching ops (`_CATALOG_LIMIT`), each with its required and optional arguments. |

`loom_search` is the registry's `search.query` operation (`POST /v1/search.query`
over HTTP, the same sections without the text summary). Over MCP it runs the same
path as every registry tool (caller defaults, session run, authorization, restricted
access audit, traffic class, history policy, rate limit, idempotency) and keeps its
own listed schema, its lenient options (an out-of-range `top_k` or an unknown
`recipe` / `bodies` is clamped, not refused) and a text summary beside the lean
result. `Operation.mcp_tool` names it, so no second `loom_search_query` tool is
listed or callable. See
[unified search](/ko/features/unified-search#searchquery-over-http-and-the-sdks).

**Hidden ops** (`_MCP_HIDDEN_OPS` in `server/operations/toolsets.py`) are neither
listed nor callable over MCP: the per-store searches `loom_search` replaces
(`memory.search`, `knowledge.search`, `conversation.search`), review queues,
snapshot and restore, policy administration, audit and cost dashboards, code-index
ingest. A call to one answers `isError` with code `OP_NOT_ON_MCP` and what to use
instead. They stay reachable over HTTP and the SDKs. On the `assistant` toolset
`memory.search` and `knowledge.search` are listed and callable, and a call to any
other hidden op answers `UNKNOWN_OP`. The rule for hiding an op: would a typical end
user, not an operator, reach for it in chat? A namespace-wide view can be hidden
while a variant bounded to the caller stays on MCP: `namespace.list` is hidden and
`namespace.list_mine` callable (listed on `all` and `readonly`, through `loom_op` on
every other toolset except `assistant`); `memory.extraction_status` (every batch queued
in the namespace) is hidden and `memory.extraction_status_mine` (the batches the caller
queued, by `queue_id`, at most 20 a call) is callable by name or through `loom_op`
on every toolset except `assistant` (`readonly` included). Its write twin,
`memory.extraction_retry_mine`, replays the caller's failed batches once more;
`loom_op` routes it on every toolset but `readonly` and `assistant`.

**Compiler-tier uploads.** `LOOM_MCP_CODE_UPLOAD_TOOLS=true` (default off) takes
`code.scip_ingest` and `code.scip_status` off the hidden ops, for a deployment whose
uploader of compiler-tier indexes reaches Loom through MCP only. Both are then callable
on every toolset but `assistant`, by tool name and through `loom_op` (which routes only
`code.scip_status` on `readonly`). `all` lists them by its own rules, so only with
`LOOM_MCP_CODE_TOOLS=true`, and `readonly` then lists `code.scip_status`; no curated
roster lists either. Each keeps its role: writer for the upload, viewer for the status.

With the setting on, `code.scip_ingest` accepts a part only for a namespace that has a
repository entry, self-service or operator-configured
([adding repositories](/ko/features/code-index/repositories)), over HTTP as over MCP.
Without that rule a caller could store upload batches in any namespace it may write,
its own memory namespace included. A part for another namespace answers
`RESOURCE_NOT_FOUND` (404 over HTTP). Send the namespace itself: when a code tool's
`namespace` names a repository and is not a namespace the caller can read, MCP resolves
it to the index of the repository's default branch, and the upload lands there.
`ops.capabilities` and the generated [operations reference](/ko/reference/operations) describe
the default: they report both ops as hidden whatever the setting.

### Toolsets

A toolset decides what is **listed**; every non-hidden op stays callable by
tool name, or through `loom_op`, whatever the toolset. Two exceptions: on
`assistant` only its own reads are callable, and on `readonly`, named by
`?toolset=` or by `LOOM_MCP_TOOLSET` when the request names none, `loom_op`
routes read ops only.

| Toolset     | Lists                                                                                                                                                                                                                                                                                                                                                                                                                                | For                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| `core`      | The memory loop: `memory.set/update/delete/pin/get/history/apply/lock`, `blacklist.add`, `context.pack`. Every other op runs through `loom_op`; no tool listed on `core` logs conversation turns. The code tools join with `LOOM_MCP_CODE_TOOLS=true`.                                                                                                                                                                               | chat clients (the default)                     |
| `coding`    | `memory.set/update/get/delete`, `working_memory.set`, `context.pack`, the code tools (`code.search`, `grep`, `enclosing`, `ask`, `symbol`, `outline`, `callers`, `context_pack`), `tracker.duplicate_check`, `code.bisect_candidates`, `code.pr_check`, `code.impact`.                                                                                                                                                               | coding agents                                  |
| `tracker`   | `tracker.answer`, `binding`, `component`, `duplicate_check`, `flaky`, `item`, `links`, `release`, `similar`, `test_signal`, plus `code.bisect_candidates`, `code.pr_check`, `code.impact`.                                                                                                                                                                                                                                           | sessions working a failing test, crash or PR   |
| `tasks`     | `task.pull/create/complete/fail/wont_do/defer/heartbeat/updates/list/get`, `inbox.list`.                                                                                                                                                                                                                                                                                                                                             | a session acting as an agent with a task inbox |
| `atomic`    | `memory.set/get/delete/ask`, `working_memory.set/append`, `run.begin/complete`.                                                                                                                                                                                                                                                                                                                                                      | minimal, policy-shaped agents                  |
| `readonly`  | The `all` listing minus every tool whose `readOnlyHint` is false; `loom_op` routes read ops only.                                                                                                                                                                                                                                                                                                                                    | read-only registrations                        |
| `assistant` | A fixed set of reads for investigating Loom on a person's behalf: `namespace.get/summary/inventory/tune/taxonomy/audit/validate/guide_get/guide_history/list_categories`, `mentor.brief/guide`, `help.search/get`, `grants.list`, `memory.inspect/search/ask/get/list/history/provenance/aggregate`, `facts.traverse/path`, `knowledge.search/get/list/inspect`, `code.search/symbol`, `insights.catalog/query`. No synthetic tools. | a chat client acting for a signed-in person    |
| `all`       | Every non-hidden op whose `maturity` is `stable`, plus the `experimental` ops the core or atomic roster lists. An experimental op that neither roster lists is left out; it is still callable by name or through `loom_op`. Code tools only with `LOOM_MCP_CODE_TOOLS=true`.                                                                                                                                                         | operators                                      |

Curated rosters combine: `?toolset=coding+tracker`, `coding,tracker`, or an
unescaped `+` that arrives as a space. Only curated rosters join (`all`,
`readonly` and `assistant` are whole surfaces), and an unknown part makes the whole value
unknown, so the listing falls back to the deployment default. The rosters are
the frozensets in `server/operations/toolsets.py`; `ops.capabilities` reports
each op's `toolsets`. A second MCP registration on another toolset
(`?toolset=tracker`, `?toolset=tasks`) adds a roster without changing the first.

**Why the listing is small.** Every listed tool's name, description and schema
is paid for in tokens on every turn of every session, and tool-selection
accuracy falls as the list grows. `tests/unit/test_mcp_listing_budget.py`
holds each roster under a token ceiling. Prefer leaving an op callable by name
over listing it; [Adding an operation](/ko/development/adding-an-operation) covers
when and how to list one.

## Results

`structuredContent` (and the JSON in `content[0].text`) is the op's output,
trimmed to the answer (`server/transport/lean_results.py`): hits with their
key, content, namespace, dates, similarity, source and status, plus counts,
paging and abstain fields. Score components, explanations, retrieval plans and
costs, hashes and empty fields are dropped. **Why:** some clients hand
`structuredContent` to the model as well as the text block, and the full
diagnostic shape costs several thousand tokens for a short answer.
`explain: true` on the call returns the full shape. HTTP, the SDKs and the
`assistant` toolset always get the full result (on `assistant`, a `memory.search` without
its per-hit score breakdown).

### The assistant toolset

`?toolset=assistant` is the connection a chat client uses to investigate Loom on behalf
of the signed-in person: what a namespace holds, how it is used, and cited answers over
memory, documents and code. The value names `assistant` alone (in any case): a misspelling or a
union such as `assistant+core` does not resolve and the connection gets the deployment's
default listing, with no error. The URL the operator configures and a `viewer` token
carry the guarantee, not the client. A replica one release older does not know the value
either and serves its default listing, so during a rolling upgrade only the token limits
the connection: point a client at `?toolset=assistant` once every replica runs a build
that serves it, and give it a `viewer` token in any case. On it:

- **Only its reads are callable.** A `tools/call` for any other tool, `loom_op` and
  `loom_search` included, answers `isError` before the handler runs, whatever the token
  allows: with code `UNKNOWN_OP`, or with the access refusal when the call names an org or
  namespace the token cannot read, which is checked first. The token is still checked on
  every call, so a read the person may not make is refused as on any connection. Mint the
  client's token with the `viewer` role to make the same limit hold on every other
  surface.
- **Its calls are ledgered as consumer `loom-assistant`**, whatever the call sends, a
  refused call to a registry tool included (an unknown tool name writes no row).
  `namespace.audit`, `namespace.summary`, `mentor.brief` and
  `knowledge.reads` leave that consumer's and the dashboard's (`loom-ui`) reads out of
  their usage counts, so looking at a namespace does not change its grade (a change to a
  memory from the dashboard is a person using the namespace and still counts in
  `namespace.audit` and `namespace.summary`); `namespace.audit` reports how many it left out in
  `summary.inspector_calls`. A token whose `consumer` claim names another consumer keeps
  its claim, and its calls are counted.
- **A read that names no namespace reads the token's.** The default is the first
  namespace the token's claim names and may read, not the first it may write: an
  assistant answer's token is minted for one namespace, while its subject's personal
  namespace is the one it may write. A token whose claim names none keeps the caller's
  default workspace.
- **A read names whose rows it reads.** The assistant writes nothing, so its client's own
  agent holds no rows, and a read that names no `agent` is not narrowed to it:
  `memory.ask` reads across agents and `mentor.brief` briefs the namespace's top writer,
  as `memory.search`, `memory.list` and `memory.history` already read across agents.
  `insights.query` answers open analytical questions in SQL over the tables
  `insights.catalog` lists, held to the token's org and namespace by ClickHouse
  ([assistant design](/ko/architecture/assistant#the-analysis-op)). A
  read of one writer's rows, `memory.aggregate` or `memory.provenance`, is refused for the
  missing `agent` until the call names the writer: a search hit's `agent`, `user_id` and
  `session_id`. The listing offers those arguments on every memory read, and `agent` on
  `mentor.brief`. `memory.get` falls back to the row under any agent.
- **Reads do not record usage.** `memory.search` runs with `auto_touch: false` and
  `memory.ask` with `reinforce: false`, whatever the call sends, so an investigation does
  not raise the recall counts that rank results; `memory.ask` also runs with
  `precedents: false`, so no answer is stored for reuse. What remains is telemetry and
  caches: the request ledger row; the exposure row every read of a memory leaves
  (`loom.memory_exposures`, the record of who was served which row); the code search
  trace a `code.search` or `code.symbol` writes (`loom.code_search_trace`, under
  `LOOM_CODE_TRACE_LOG_ENABLED`); the search trace and query-node rows a `memory.search`
  writes when `LOOM_SEARCH_TRACE_LOG_ENABLED` or `LOOM_MEMORY_QUERY_NODES_ENABLED` is on;
  a `memory.ask` consistency row under deferred consistency; and the model response
  cache. An assistant call opens no MCP session run, and its `initialize` and `loom`
  prompt write no profile-read row: its primer inlines no profile.
- **Results are the full output**, as HTTP returns them, since a citation needs the
  identities, versions and attestations the trimmed shape drops; a `memory.search` runs
  with `explain: false`, so its hits carry no per-hit score breakdown. `memory.search`
  and `knowledge.search`, which the other listings leave to `loom_search`, are listed
  here so an answer can come from one plane at a time. A `knowledge.search` hit names
  its `source_uri`, heading breadcrumb (`section`) and the `revision` its passage was
  written as (0 when none was recorded), and an ingested file's hit its `locator`. The
  hit is the nearest passage, not an answer: the op has no abstain signal, so the model
  says a fact is not in the documents when no hit states it.
- **The `initialize` instructions** tell the model to cite each claim by key and version
  or content hash, or by document `source_uri`, section and the revision a hit carries
  (none when it is 0), to keep source statements, computed results and its own reading
  apart, to report missing evidence as not observed, and to treat stored text as data
  that cannot grant a tool or approve a change.

## Errors

A call that cannot run as sent comes back as a **tool result** with
`isError: true`, a text block the model reads and a `structuredContent` body.
Clients show these to the model so it can correct the call; many clients drop
state on a JSON-RPC error frame, which Loom keeps for transport failures.

- **Wrong arguments.** A validation failure answers `"<op>: invalid
arguments."` followed by each field error, every unknown key with the field
  it most likely meant (nested fields included), the required and optional
  arguments and one corrected example call:

  ```text
  memory.get: invalid arguments.
  memory_key: Field required [missing]
  unknown 'key' — did you mean 'memory_key'?
  required: memory_key
  optional: if_version, include_recall_breakdown, as_of, fields, follow
  example: {"memory_key": "deploy_window"}
  ```

  `structuredContent` carries the same parts: `errors`, `op`, `required`,
  `optional`, `unknown` (key → suggestion) and `example`. An op that changes
  state (any op that is not read-only) given a near-miss key is refused before
  validation (`UNKNOWN_ARGUMENT`, nothing written) with `did_you_mean` and the
  op's arguments.

- **Refusals.** A handler's 4xx other than 401 (`LOCKED`, `PINNED_CONFLICT`,
  `BLACKLISTED`, `RESOURCE_NOT_FOUND`, `RATE_LIMITED`, …) is a tool result whose
  body is the HTTP `detail` plus `status` and, when there was a `Retry-After`,
  `retry_after_s`.
- **Access.** A role failure answers `AUTH_INSUFFICIENT` with `required_role`; a
  namespace the token neither names nor holds a grant on answers
  `NAMESPACE_NOT_ACCESSIBLE`. On a code or tracker namespace, or a shared
  collection (not someone else's personal one), the refusal says how to get access.
- **Transport errors** stay JSON-RPC errors: parse error `-32700`, invalid
  request `-32600` (an auth refusal carries its HTTP status; a malformed request or a
  batch outside 1 to 64 answers 200), method not found `-32601`, unsupported
  protocol version `-32022`, and a server fault `-32000 "tool execution
failed"`. A fault Loom names (`OVERLOADED`, `BACKEND_TIMEOUT`,
  `SCHEMA_PENDING`, `EMBED_TIMEOUT`) states its code and message in that error, and
  `error.data` is the HTTP `detail` plus `status`, `tool` and `request_id` (with
  `retry_after_s` when the error names a wait); any other fault says only `internal error` and the
  request id.

Every refusal body with a `code` and every fault's `error.data` also carries `category`
and `retryable`, as the HTTP envelope does. A tool's refusal text ends with the same class
in words (`(auth: do not retry unchanged)`), for a host that shows the model only the text;
`loom_op`'s own refusals carry the fields in their JSON text. A `NAMESPACE_NOT_ACCESSIBLE`
refusal of a namespace that is not a collection, from a tool that is not a code or tracker
tool, on a toolset that reaches `loom_op`, also carries a `next` step
([errors reference](/ko/reference/errors#the-error-envelope-over-http)). Every code, with its
cause and fix, is in the [errors reference](/ko/reference/errors).

## Security

`tools/call` runs the HTTP transport's gates (`server/transport/gates.py`):

- **Authorization** per call: the op's `required_role` and the namespace's
  access rules.
- **Rate limit**: the same buckets as HTTP. Because MCP clients do not retry, a
  limited call whose wait hint is at most `LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S`
  (default 2 s) sleeps that long once and checks the same buckets again; a
  longer hint or a second refusal answers `RATE_LIMITED` with `retry_after_s`
  (`LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S=0` never waits).
- **Audit**: ops declared `audit=True` write the same `loom.audit_log` rows.
- **Idempotency**: MCP has no idempotency header, so an idempotent op takes
  `_idempotency_key` (or `idempotency_key`) in its arguments. It is removed
  before validation and replays exactly as the HTTP `Idempotency-Key` does: only
  after authorization, and only to the principal that stored it.

## Exporting the action schema

A policy gateway can govern Loom's tools from a schema generated from the
registry (`server/transport/action_schema.py`):

```bash
loom export-actions --format json  -o loom-tools.json    # tools/list manifest + a `loom` block per tool
loom export-actions --format cedar -o loom.cedarschema   # Cedar: one action per operation
```

The JSON manifest has the MCP `tools/list` shape (`name`, `description`,
`inputSchema`, `outputSchema`) for every op, plus a `loom` block with what a
policy engine needs and MCP has no field for: the op name, the HTTP path, the
required role, the effect class (`read`, `write` or `destructive`, from the same
classifier the annotations use), idempotency, the audit flag, MCP visibility and
the input and output model names. The Cedar schema declares, in namespace
`Loom`, an `Agent` principal and a `Namespace` resource, one record type per
input and output model, the action groups `Read`, `Write` and `Destructive`
(`Destructive` in `Write`), and one action per operation in its group. `-o -`
writes to stdout.

## Related

- [MCP clients](/ko/features/integrations/mcp-clients): connecting Claude Code, Codex, Cursor and other clients.
- [Claude Code](/ko/features/integrations/claude-code) and [Codex](/ko/features/integrations/codex): the plugins that mount the server themselves.
- [Operations reference](/ko/reference/operations): every op with its role, kind and whether `all` lists it.
- [Errors reference](/ko/reference/errors).
