未翻訳のページは英語で開き、英語と表示されます。
この機械翻訳の作成後に英語の原文が更新されています。最新の手順は英語のページを参照してください。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
MCP リファレンス
Loom は、その操作を MCP ツールとして <loom>/mcp で提供します。streamable HTTP に対応した MCP クライアントであれば、URL とベアラートークンで接続できます。ツール一覧は HTTP API と同じ操作レジストリから生成されます。ツール呼び出しは、POST /v1/<op> と同じ認可、レート制限、監査、冪等性の経路で実行されます。トランスポートは server/transport/mcp.py で、ツール呼び出しは mcp_call.py と mcp_outcome.py、ベアラートークンの検証は mcp_auth.py、一覧表示は mcp_tools.py、スキーマの整形は mcp_schemas.py、プロトコルとセッションの定数は mcp_config.py、厳選された説明文は mcp_descriptions.py にあります。
特定のクライアント(Claude Code、Codex、Cursor、VS Code、Claude Desktop など)を loom install または手動で設定する方法は、MCP クライアントを参照してください。
エンドポイント
| リクエスト | 動作 |
|---|---|
POST /mcp |
JSON-RPC リクエスト 1 件、または 1 〜 64 件のバッチを受け付けます。応答はイベントストリームではなく JSON ボディです。通知には本文なしの 202 を返します。 |
DELETE /mcp + Mcp-Session-Id |
セッションを終了し、そのセッションの暗黙の run を閉じます。run.complete として、組織の予算の範囲内で呼び出し元ごとにレート制限されます。上限を超えると Retry-After 付きの 429 を返します。 |
URL のクエリパラメータで、その接続で tools/list が表示する内容を選択します。
?toolset=は、一覧に表示するツールの構成を選びます(ツールセット)。デフォルトはLOOM_MCP_TOOLSET(core)です。?schema_profile=は、一覧の形式を選びます。standard(整えられた説明と入力スキーマ。デフォルトで、LOOM_MCP_SCHEMA_PROFILE)、full(outputSchemaを追加)、compact(最初の段落と引数ツリー)があります。
どちらも未知の値を指定した場合はデプロイメントのデフォルトにフォールバックするため、タイプミスによって一覧が気付かないうちに広がったり狭まったりすることはありません。?toolset= の値は、セッションのプライマー(initialize の instructions、server/discover、loom プロンプト、loom://primer、loom_activate)の内容にも影響します。プライマーは、ツールセットに op 専用のツールがあればそのツール名を示し、なければ「(via loom_op)」と付けた op 名を示します。loom_op がそこへルーティングしない op は省略されます。
対応するメソッドは initialize、notifications/initialized、notifications/cancelled、ping、tools/list、tools/call、prompts/list、prompts/get(loom プロンプト:セッションのプライマー)、resources/list、resources/read(loom://primer)、server/discover です。一覧の結果には ttlMs と cacheScope のヒントが含まれ、クライアントはこれをもとにキャッシュできます。
プロトコルバージョン。 2025-11-25、2025-06-18、2025-03-26、2024-11-05 に対応しています(MCP_SUPPORTED_PROTOCOL_VERSIONS)。initialize は、クライアントのバージョンがこれらのいずれかであればそのバージョンで応答し、それ以外の場合は 2025-11-25 で応答します。MCP-Protocol-Version ヘッダーが他のリビジョンを指定している場合は HTTP 400 と JSON-RPC エラー -32022 を返し、data.supported に対応バージョンの一覧が入ります。server/discover は、同じバージョン一覧に加えて、capabilities、サーバー識別情報、instructions を返します。
認証
LOOM_MCP_AUTH_MODE が、どのメソッドにベアラーが必要かを決めます。
| モード | ベアラーが必要なメソッド |
|---|---|
required(デフォルト) |
通知を除くすべてのメソッド |
discovery_only |
tools/call のみ。それ以外のメソッドはすべて公開 |
open |
なし。無効なベアラーは無視されます(信頼できるネットワーク専用) |
ループバック以外の LOOM_BIND_HOST 上のサーバーは、LOOM_ALLOW_INSECURE=1 でない限り open では起動を拒否します。認証をオフにしたデプロイ(LOOM_AUTH_REQUIRED=false)は open と同じ動作になります。ゲートされたメソッドでベアラーがない、または無効な場合は、HTTP 401 と WWW-Authenticate: Bearer realm="loom" が返ります(トークンが送信されていた場合は error="invalid_token" も付きます)。失効リストが未読み込みのためにトークンをまだ検証できない場合は、代わりに Retry-After 付きの HTTP 503 が返り、クライアントはトークンを保持したまま再試行します。JSON-RPC エラーではなく 401 である理由: クライアントは「認証が必要」というフローや OAuth ディスカバリを HTTP ステータスで判定します。JSON-RPC のエラー本文では、パースエラーやツールエラーとして扱われてしまいます。トークンは通常の Loom JWT です。詳しくはトークンとグラントを参照してください。
ベアラーは Authorization ヘッダーからのみ読み取られます。/mcp の URL に ?token= として渡されたトークンは無視され、リクエストは未認証として扱われます。リクエストラインはプロキシやアクセスログに残るため、URL 内のトークンは平文で記録されてしまうからです。
OAuth
LOOM_OAUTH_ENABLED=true の場合にのみ提供されます。Loom は、トークンを貼り付ける代わりにブラウザーのサインインで接続するクライアント向けの OAuth 2.1 認可サーバーです(server/auth/oauth.py)。
- ディスカバリは
/.well-known/oauth-authorization-serverと/.well-known/oauth-protected-resourceにあります。 - 動的クライアント登録は
/oauth/registerで行います。パブリッククライアントが対象で、PKCES256が必須です。 /oauth/authorizeと/oauth/tokenは、アクセストークンとローテーションされるリフレッシュトークンを発行します。リフレッシュが成功するのは、リクエストがトークンの発行先のclient_idを指定している場合のみです。- アクセストークンはサインインしたユーザー向けの Loom JWT なので、ユーザーが後から参加した名前空間も同じ接続で利用できます。
- サインインには Loom のパスワードログインを使います。
LOOM_OAUTH_LOGIN_PROVIDER=oidcを設定すると、外部のアイデンティティプロバイダーに委任されます(LOOM_OIDC_ISSUER、LOOM_OIDC_CLIENT_ID、LOOM_OIDC_CLIENT_SECRET)。サインインを委任すると、パスワードによるセルフサインアップも無効になります。 - リモートのデプロイでは HTTPS で提供し、
LOOM_OAUTH_ISSUERを公開用のhttps://ベース URL に設定する必要があります。 - 登録するリダイレクト URI は絶対 URI で、フラグメントを含んではいけません。使えるのは
https、ループバックホストへのhttp、またはアプリスキーム(cursor://…)です。サインインページには、認可の送信先ホストが表示されます。 - リフレッシュのたびに、アカウントが引き続き有効かを再確認し、ロールを再導出します。そのため、解放されたアカウントや
LOOM_PLATFORM_ADMINSから削除されたサブジェクトは、リフレッシュしてもアクセス権を維持できません。
この背後にあるトークンモデルについては、セキュリティを参照してください。
セッションと ID
- セッション ID。
initializeはMcp-Session-Idを割り当て、すべてのレスポンスがそれを返します。クライアントのclientInfo.nameはこの ID に対してキャッシュされ、スラッグ化されて以降の呼び出しのagentになります(Cursor→cursor、未指定の場合はclaude-desktop)。キャッシュはプロセス内に置かれ、サイズに上限があります。 - ID のデフォルト値。 ツール呼び出しには通常、アクションの引数だけが含まれます。サーバーは
orgをトークンから、namespaceとagentを呼び出し元のデフォルトワークスペースから補完します。明示的に指定した引数が優先されます。code.*の呼び出しは代わりにコードプレーンに解決され、assistantツールセットでは、namespaceまたはagentを指定しない読み取りはそのツールセットのルールに従います(assistant ツールセットを参照)。トークンが操作を許可されていないorg引数は拒否されます(ORG_MISMATCH)。トークンは自身の org 内で操作でき、org 全体(*)のトークンまたはプラットフォーム管理者は任意の org で操作できます。これは HTTP 経由の場合と同じルールです(authz.may_act_in_org)。制限付きの名前空間は、プラットフォーム管理者を含め、他のすべての org を引き続き拒否します。loom_searchはnamespace引数を取りません。呼び出し元のホーム名前空間と、メモリ種別が同じ他の名前空間を、ファンアウトの上限まで検索します。 - コードスコープ。 クライアントは
X-Loom-Code-Scope: <org>/<namespace>を送信できます(Claude Code プラグインは、チェックアウトが解決されたリポジトリを送信します)。これは名前空間を指定しないすべてのcode.*呼び出しに適用され、認可はその名前空間が指定されたものとして実行されます。このヘッダーがある場合、loom_searchは、呼び出し元に読み取り権限があれば、リポジトリのドキュメントとdecisionメモリもそのトランク用コード名前空間から読み取り、不具合の形をしたクエリに対してはトラッカーの重複チェックを実行します。 - 暗黙の run。 run は (org、トークンのサブジェクト、セッション) ごとに 1 つです。セッションで最初に run スコープのツール呼び出しが行われた時点で run 台帳に開始され、呼び出し元のデフォルト名前空間に記録されます。書き込みにはその
run_idが付与されます(ただし、自身の run を指定するrun.*、デプロイメントのコード ID として動作するcode.*、run_idが行のスコープ指定または紐付けに使われるworking_memory.*とconversation.updateは除きます)。読み取りにはその ID がラベルとして付きますが、絞り込みは行われません。run はDELETE /mcpで終了するほか、mcp_session_run_sweepワーカーが、その run に属するトークンの呼び出しをLOOM_MCP_SESSION_RUN_IDLE_SECONDS(デフォルト 1800)の間確認できなかった場合にも終了します。バックグラウンドワーカーをどこでも実行していないデプロイメントでは、アイドル状態の run は開いたままになります。run は呼び出し回数を保持しません。その呼び出しは、run_idが一致するagent_eventsの行です。実行(Runs)を参照してください。
ツール一覧
_MCP_HIDDEN_OPS に含まれないレジストリのすべてのオペレーションがツールになります。
- 名前。
loom_に、ドットをアンダースコアに置き換えた op 名を続けたものです(memory.set→loom_memory_set)。 - 説明。
TOOL_DESCRIPTIONS(server/transport/mcp_descriptions.py)に厳選された文があればそれを使い、なければ op のレイテンシ予算、冪等性、最小ロールを含む 1 行のフォールバックを使います。厳選された文には、そのツールをいつ使うか、いつ使わないかが書かれており、選択はモデルに委ねられます。文中では他の op を op 名で参照し、各一覧はそれを読むクライアント向けに描画します(server/transport/mcp_op.pyのname_ops_for_listing)。一覧に含まれる op はそのツール名(loom_memory_update)で参照されます。一覧に含まれない op は、loom_opが受け取る op 名のままとなり、その接続でloom_opがその op をルーティングする場合は、最初の言及の後ろに「(via loom_op)」が付きます。非表示の op、readonlyでの書き込み、assistantでのあらゆる op はルーティングされません。入力フィールドの説明、fullプロファイルが保持する出力スキーマ、非表示 op のinsteadテキストも同じ方法で描画されます。op 名について書かれたloom_op自身のテキストは、代わりに一覧ごとに組み立てられます。メンターテキストは、MCP 経由でも呼び出し元の一覧向けに描画されます(ツール結果のhint、context.packのmentorセクション、mentor.briefのヒントとプレーンのwhen)。HTTP 経由では保存されたとおりに読み取られます。 - 入力スキーマ。 op の Pydantic 入力モデルから、サーバーが自分で埋めるフィールド(
org、agent、user_id、session_id、consumer)、ダッシュボード専用フィールド(server/transport/mcp_schemas.pyの_HIDDEN_OP_PROPS)、MCP_HIDDENが付いたすべてのフィールドを除いたものです。namespaceは任意のプロパティとして残ります。非表示フィールドも名前を指定すれば受け付けられます。 - アノテーション。
readOnlyHint、destructiveHint、idempotentHintはレジストリ(ロール、冪等性、監査、名前に含まれる破壊的な動詞)から導出されます。readOnlyHintが true になるのは、冪等な viewer の op で、監査対象でもwritesが付けられてもいないものだけです。そのため、読み取り専用ツールを自動承認するクライアントが、状態変更を確認なしに実行することはありません。これらはヒントであり、境界となるのは呼び出し時のロールチェックです。
assistant を除くすべてのツールセットで、3 つの合成ツールが一覧に表示されます。
| ツール | 動作 |
|---|---|
loom_search |
1 回の呼び出しで、メモリ、プロファイル、ナレッジ、会話を並列に検索し、4 つのセクションすべてを返します。explain: true を指定すると、各メモリヒットがなぜその順位になったかが追加されます。 |
loom_activate |
セッションのプライマー(プロファイル、設定、デフォルトのワークスペース)を返します。内容は loom プロンプトと同じテキストです。 |
loom_op |
{op, arguments} で、ロスターに載っていない任意の op を、一覧に載っているツールと同じ経路で実行します。{op: "help", query} は、一致する op を最大 15 件(_CATALOG_LIMIT)、必須引数と任意引数とともに一覧表示します。 |
loom_search はレジストリの search.query オペレーションです(HTTP では POST /v1/search.query。テキストサマリーを除いた同じセクションを返します)。MCP 経由では、他のすべてのレジストリツールと同じ経路(呼び出し元のデフォルト、セッション実行、認可、制限付きアクセスの監査、トラフィッククラス、履歴ポリシー、レート制限、冪等性)を通り、独自の一覧用スキーマ、寛容なオプション(範囲外の top_k や未知の recipe / bodies は拒否されず補正されます)、そして簡潔な結果と並ぶテキストサマリーを備えます。Operation.mcp_tool がこの名前を指定するため、2 つ目の loom_search_query ツールが一覧に載ることも、呼び出し可能になることもありません。詳しくは統合検索を参照してください。
非表示 op(server/operations/toolsets.py の _MCP_HIDDEN_OPS)は、MCP では一覧に載らず、呼び出すこともできません。対象は、loom_search が置き換えるストア別の検索(memory.search、knowledge.search、conversation.search)、レビューキュー、スナップショットとリストア、ポリシー管理、監査・コストのダッシュボード、コードインデックスの取り込みです。これらを呼び出すと、コード OP_NOT_ON_MCP と代わりに使うべきものを添えた isError が返ります。HTTP と SDK からは引き続き利用できます。assistant ツールセットでは memory.search と knowledge.search が一覧に載り呼び出し可能で、他の非表示 op を呼び出すと UNKNOWN_OP が返ります。op を隠す基準は、一般的なエンドユーザー(オペレーターではなく)がチャットで使おうとするかどうかです。名前空間全体のビューは隠しつつ、呼び出し元に限定した派生版を MCP に残す場合があります。namespace.list は非表示で、namespace.list_mine は呼び出し可能です(all と readonly では一覧に載り、assistant を除く他のすべてのツールセットでは loom_op 経由で利用できます)。memory.extraction_status(名前空間内でキューに入っているすべてのバッチ)は非表示で、memory.extraction_status_mine(呼び出し元がキューに入れたバッチを queue_id で指定、1 回の呼び出しで最大 20 件)は、assistant を除くすべてのツールセット(readonly を含む)で、名前指定または loom_op 経由で呼び出せます。その書き込み側の対となる memory.extraction_retry_mine は、呼び出し元の失敗したバッチをもう一度再実行します。loom_op は、readonly と assistant を除くすべてのツールセットでこれをルーティングします。
ツールセット
ツールセットが決めるのは何が一覧に載るかです。非表示でないすべての op は、ツールセットに関係なく、ツール名または loom_op 経由で呼び出せます。例外は 2 つあります。assistant では自身の読み取り op だけが呼び出し可能です。また readonly を ?toolset= で指定した場合、またはリクエストが指定しないときに LOOM_MCP_TOOLSET で指定した場合、loom_op は読み取り op だけをルーティングします。
| ツールセット | 一覧に載るもの | 用途 |
|---|---|---|
core |
メモリのループ:memory.set/update/delete/pin/get/history/apply/lock、blacklist.add、context.pack。他のすべての op は loom_op 経由で実行されます。core に載るツールに、会話ターンを記録するものはありません。コードツールは LOOM_MCP_CODE_TOOLS=true で追加されます。 |
チャットクライアント(デフォルト) |
coding |
memory.set/update/get/delete、working_memory.set、context.pack、コードツール(code.search、grep、enclosing、ask、symbol、outline、callers、context_pack)、tracker.duplicate_check、code.bisect_candidates、code.pr_check、code.impact。 |
コーディングエージェント |
tracker |
tracker.answer、binding、component、duplicate_check、flaky、item、links、release、similar、test_signal、加えて code.bisect_candidates、code.pr_check、code.impact。 |
失敗したテスト、クラッシュ、PR を扱うセッション |
tasks |
task.pull/create/complete/fail/wont_do/defer/heartbeat/updates/list/get、inbox.list。 |
タスクインボックスを持つエージェントとして動くセッション |
atomic |
memory.set/get/delete/ask、working_memory.set/append、run.begin/complete。 |
最小構成の、ポリシーで形作られたエージェント |
readonly |
all の一覧から、readOnlyHint が false のツールをすべて除いたもの。loom_op は読み取り op だけをルーティングします。 |
読み取り専用の登録 |
assistant |
ユーザーに代わって Loom を調査するための固定の読み取りセット: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。合成ツールはありません。 |
サインイン済みのユーザーのために動くチャットクライアント |
all |
maturity が stable である非表示でないすべての op に、core または atomic のロスターが載せている experimental の op を加えたもの。どちらのロスターにも載っていない experimental の op は一覧から外れますが、名前指定または loom_op 経由では呼び出せます。コードツールは LOOM_MCP_CODE_TOOLS=true のときだけ含まれます。 |
オペレーター |
厳選されたロスターは組み合わせられます。?toolset=coding+tracker、coding,tracker、またはスペースとして届くエスケープされていない + を使います。組み合わせられるのは厳選されたロスターだけで(all、readonly、assistant は全体を表すため不可)、未知の部分が 1 つでもあると値全体が未知として扱われ、一覧はデプロイメントのデフォルトに戻ります。ロスターは server/operations/toolsets.py の frozenset です。ops.capabilities は各 op の toolsets を報告します。別のツールセットでの 2 つ目の MCP 登録(?toolset=tracker、?toolset=tasks)は、最初の登録を変えずにロスターを追加します。
一覧が小さい理由。 一覧に載るすべてのツールの名前、説明、スキーマは、すべてのセッションのすべてのターンでトークンとして消費され、一覧が長くなるほどツール選択の精度は下がります。tests/unit/test_mcp_listing_budget.py は、各ロスターをトークン上限以下に保ちます。op は一覧に載せるより、名前指定で呼び出せる状態にしておくほうを選んでください。一覧に載せる場合とその方法については、オペレーションの追加を参照してください。
結果
structuredContent(および content[0].text 内の JSON)は op の出力で、回答に必要な部分だけに絞られています(server/transport/lean_results.py)。ヒットにはキー、内容、名前空間、日付、類似度、ソース、ステータスが含まれ、そのほかに件数、ページング、abstain 関連のフィールドが含まれます。スコアの内訳、説明、検索プランとコスト、ハッシュ、空のフィールドは除かれます。理由: 一部のクライアントは structuredContent をテキストブロックに加えてモデルにも渡します。診断情報を含む完全な形式では、短い回答でも数千トークンかかります。呼び出しに explain: true を指定すると完全な形式が返ります。HTTP、SDK、assistant ツールセットは常に完全な結果を受け取ります(assistant では、memory.search からヒットごとのスコア内訳を除いたものです)。
assistant ツールセット
?toolset=assistant は、チャットクライアントがサインイン中のユーザーに代わって Loom を調べるための接続です。名前空間に何が入っているか、どう使われているか、そしてメモリ、ドキュメント、コードに対する引用付きの回答を扱います。値として指定できるのは assistant のみです(大文字小文字は問いません)。綴りを誤った場合や assistant+core のような組み合わせは解決されず、エラーなしでデプロイメントのデフォルトの一覧が返されます。保証を担うのはクライアントではなく、オペレーターが設定した URL と viewer トークンです。1 リリース古いレプリカもこの値を知らないため、デフォルトの一覧を返します。そのためローリングアップグレード中に接続を制限するのはトークンだけです。クライアントを ?toolset=assistant に向けるのは、すべてのレプリカがこれに対応したビルドで動作してからにし、いずれにしても viewer トークンを渡してください。この接続では次のとおりです。
- 呼び出せるのは読み取りだけです。 それ以外のツール(
loom_opとloom_searchを含む)へのtools/callは、ハンドラーが動く前にisErrorで応答します。トークンが許可しているかどうかは関係ありません。コードはUNKNOWN_OPです。ただし、トークンが読み取れない組織や名前空間を呼び出しが指定している場合は、アクセス拒否が返ります。こちらが先に確認されます。トークンは呼び出しごとに引き続き確認されるため、ユーザーに許されていない読み取りは、ほかの接続と同様に拒否されます。クライアントのトークンをviewerロールで発行すると、同じ制限がほかのすべてのサーフェスでも有効になります。 - 呼び出しはコンシューマー
loom-assistantとして台帳に記録されます。 呼び出しが何を送っても同じです。レジストリのツールへの拒否された呼び出しも含まれます(不明なツール名では行が書かれません)。namespace.audit、namespace.summary、mentor.brief、knowledge.readsは、このコンシューマーとダッシュボード(loom-ui)の読み取りを使用回数の集計から除外します。そのため、名前空間を見ても評価は変わりません(ダッシュボードからのメモリの変更は、ユーザーが名前空間を使ったものとして、namespace.auditとnamespace.summaryに引き続き数えられます)。namespace.auditは、除外した件数をsummary.inspector_callsで報告します。consumerクレームがほかのコンシューマーを指すトークンは、そのクレームが保たれ、その呼び出しは集計されます。 - 名前空間を指定しない読み取りは、トークンの名前空間を読みます。 デフォルトは、トークンのクレームが指す名前空間のうち、読み取りが許されている最初のものです。書き込みが許されている最初のものではありません。assistant の回答用トークンは 1 つの名前空間向けに発行され、その対象者の個人名前空間が書き込み可能な名前空間になるためです。クレームがどの名前空間も指さないトークンでは、呼び出し元のデフォルトのワークスペースが保たれます。
- 読み取りは、どの行を読むかを指定します。 assistant は何も書き込まないため、クライアント側のエージェントは行を持ちません。そのため
agentを指定しない読み取りは、エージェントで絞り込まれません。memory.askはエージェントをまたいで読み、mentor.briefは名前空間で最も多く書き込んだ書き手についてブリーフを作ります。memory.search、memory.list、memory.historyがすでにエージェントをまたいで読むのと同じです。insights.queryは、insights.catalogが一覧するテーブルに対する SQL で、自由な分析上の問いに答えます。トークンの組織と名前空間の範囲は ClickHouse が保証します(assistant の設計)。特定の書き手の行を読むmemory.aggregateとmemory.provenanceは、呼び出しが書き手を指定するまで、agentがないとして拒否されます。書き手は、検索ヒットのagent、user_id、session_idから分かります。一覧では、これらの引数がすべてのメモリ読み取りに用意され、mentor.briefにはagentが用意されています。memory.getは、どのエージェントの行であっても取得できます。 - 読み取りは使用状況を記録しません。
memory.searchはauto_touch: falseで、memory.askはreinforce: falseで実行されます。呼び出しが何を送っても同じです。そのため調査によって、結果の順位づけに使われる想起回数が増えることはありません。memory.askはprecedents: falseでも実行されるので、再利用のために回答が保存されることもありません。残るのはテレメトリとキャッシュです。リクエスト台帳の行、メモリを読むたびに残る露出行(loom.memory_exposures、どの行を誰に提供したかの記録)、code.searchやcode.symbolが書くコード検索トレース(loom.code_search_trace、LOOM_CODE_TRACE_LOG_ENABLEDが有効な場合)、LOOM_SEARCH_TRACE_LOG_ENABLEDまたはLOOM_MEMORY_QUERY_NODES_ENABLEDが有効なときにmemory.searchが書く検索トレースとクエリノードの行、遅延整合性の下でのmemory.askの整合性行、モデルのレスポンスキャッシュです。assistant の呼び出しは MCP セッションの run を開きません。またinitializeとloomプロンプトはプロファイル読み取りの行を書きません。プライマーにプロファイルが埋め込まれないためです。 - 結果は完全な出力です。 HTTP が返すものと同じです。引用には、絞り込まれた形式が落とす ID、バージョン、証明が必要なためです。
memory.searchはexplain: falseで実行されるため、そのヒットにはヒットごとのスコア内訳がありません。ほかの一覧ではloom_searchに任されているmemory.searchとknowledge.searchが、ここでは一覧に含まれます。これにより、回答を 1 つのプレーンから取得できます。knowledge.searchのヒットには、source_uri、見出しのパンくず(section)、その一節が書かれたときのrevision(記録がなければ 0)が含まれ、取り込まれたファイルのヒットにはlocatorが含まれます。ヒットは最も近い一節であり、回答ではありません。この op には abstain のシグナルがないため、どのヒットにも書かれていない事実については、モデルがドキュメントにないと答えます。 initializeの指示は、モデルに次のことを求めます。 各主張をキーとバージョンまたはコンテンツハッシュで引用すること、あるいはドキュメントのsource_uri、セクション、ヒットが持つ revision(0 の場合はなし)で引用すること。ソースの記述、計算結果、自身の解釈を区別すること。証拠がないことは未観測として報告すること。保存されたテキストはデータとして扱い、ツールを許可したり変更を承認したりできないものとすること。
エラー
送信されたとおりには実行できない呼び出しは、isError: true を持つ tool result として返ります。これは、モデルが読むテキストブロックと structuredContent の本体で構成されます。クライアントはこれらをモデルに見せ、モデルが呼び出しを修正できるようにします。多くのクライアントは JSON-RPC のエラーフレームを受け取ると状態を破棄するため、Loom はエラーフレームをトランスポート障害に限って使います。
-
引数の誤り。 検証に失敗すると、
"<op>: invalid arguments."に続けて、各フィールドのエラー、未知のキーごとに本来指していたと思われるフィールド(ネストしたフィールドを含む)、必須引数と任意引数、修正済みの呼び出し例を 1 つ返します。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には同じ内容がerrors、op、required、optional、unknown(キー → 候補)、exampleとして入ります。状態を変更する op(読み取り専用でない op)に、綴りの近い誤ったキーが渡された場合は、検証の前に拒否されます(UNKNOWN_ARGUMENT、何も書き込まれません)。このときdid_you_meanと op の引数が返ります。
- 拒否。 401 以外のハンドラの 4xx(
LOCKED、PINNED_CONFLICT、BLACKLISTED、RESOURCE_NOT_FOUND、RATE_LIMITEDなど)は tool result として返ります。本体は HTTP のdetailにstatusを加えたもので、Retry-Afterがあった場合はretry_after_sも含みます。 - アクセス。 ロールが不足している場合は
AUTH_INSUFFICIENTとrequired_roleを返します。トークンが名指ししておらず、かつ許可も持たない名前空間に対してはNAMESPACE_NOT_ACCESSIBLEを返します。コードまたはトラッカーの名前空間、あるいは共有コレクション(他のユーザーの個人用コレクションを除く)では、拒否メッセージにアクセスを得る方法が示されます。 - トランスポートエラー は JSON-RPC エラーのままです。パースエラーは
-32700、不正なリクエストは-32600(認証の拒否には HTTP ステータスが付きます。形式の誤ったリクエストや、1〜64 の範囲外のバッチには 200 を返します)、メソッドが見つからない場合は-32601、未対応のプロトコルバージョンは-32022、サーバー障害は-32000 "tool execution failed"です。Loom が名前を付けている障害(OVERLOADED、BACKEND_TIMEOUT、SCHEMA_PENDING、EMBED_TIMEOUT)では、そのエラーにコードとメッセージが示され、error.dataは HTTP のdetailにstatus、tool、request_idを加えたものになります(待機時間を示すエラーではretry_after_sも付きます)。それ以外の障害ではinternal errorとリクエスト ID のみが示されます。
code を持つすべての拒否本体と、すべての障害の error.data には、HTTP エンベロープと同様に category と retryable も含まれます。テキストしかモデルに見せないホストのために、ツールの拒否テキストの末尾には同じ分類が言葉で付きます((auth: do not retry unchanged))。loom_op 自身の拒否では、これらのフィールドが JSON テキストに含まれます。コレクションではない名前空間に対する NAMESPACE_NOT_ACCESSIBLE の拒否が、コードまたはトラッカーのツールではないツールから、loom_op に到達できるツールセットで発生した場合は、next ステップも付きます(エラーリファレンス)。すべてのコードと、その原因および対処はエラーリファレンスにあります。
セキュリティ
tools/call は HTTP トランスポートのゲート(server/transport/gates.py)を実行します。
- 認可:呼び出しごとに、op の
required_roleと名前空間のアクセスルールを確認します。 - レート制限:HTTP と同じバケットを使用します。MCP クライアントは再試行しないため、待機ヒントが
LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S(デフォルトは 2 秒)以下で制限された呼び出しは、その時間だけ一度スリープし、同じバケットを再度確認します。ヒントがそれより長い場合、または 2 回目も拒否された場合は、retry_after_sを付けてRATE_LIMITEDを返します(LOOM_MCP_RATELIMIT_RETRY_MAX_WAIT_S=0の場合は待機しません)。 - 監査:
audit=Trueと宣言された op は、同じloom.audit_logの行を書き込みます。 - 冪等性:MCP には冪等性ヘッダーがないため、冪等な op は引数に
_idempotency_key(またはidempotency_key)を取ります。このキーは検証の前に取り除かれ、HTTP のIdempotency-Keyとまったく同じようにリプレイされます。リプレイは認可の後にのみ行われ、キーを保存したプリンシパルに対してのみ行われます。
アクションスキーマのエクスポート
ポリシーゲートウェイは、レジストリから生成したスキーマ(server/transport/action_schema.py)を使って、Loom のツールを制御できます。
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
JSON マニフェストは、すべての op について MCP の tools/list 形式(name、description、inputSchema、outputSchema)を持ち、さらにポリシーエンジンが必要とするものの MCP にはフィールドがない情報を収めた loom ブロックを含みます。内容は、op 名、HTTP パス、必要なロール、効果クラス(read、write、destructive。アノテーションと同じ分類器によるもの)、冪等性、監査フラグ、MCP での可視性、入力モデル名と出力モデル名です。Cedar スキーマでは、名前空間 Loom に、プリンシパル Agent とリソース Namespace、入力モデルと出力モデルごとに 1 つのレコード型、アクショングループ Read、Write、Destructive(Destructive は Write に含まれます)、そして各操作に対応するアクションをそれぞれのグループ内に宣言します。-o - を指定すると標準出力に書き出します。
関連情報
- MCP クライアント:Claude Code、Codex、Cursor などのクライアントを接続する方法。
- Claude Code と Codex:サーバーを自動でマウントするプラグイン。
- オペレーションリファレンス:すべての op とそのロール、種類、
allで一覧表示されるかどうか。 - エラーリファレンス。