AXIOM

@codai/axiom-mcp

コーディングエージェント向けのトランザクション型書き込みゲート、AXIOM v2 用の MCP サーバー（stdio または Streamable HTTP）と CLI です： Plan → 正規の ManifestBundle → セットレベルのチェック → ハッシュでゲートされた二段階の apply → ジャーナル。 dist/cli.js（薄いエントリーポイント）＋ dist/cli-main.js（遅延読み込みされるエンジン。MCP SDK v2 と zod は mcp-lazy / http-lazy チャンクにバンドルされています）。ランタイム依存関係はありません。

インストールと実行

npx @codai/axiom-mcp mcp --root /abs/path/to/repo          # stdio MCP server
npx @codai/axiom-mcp mcp --root /abs/path/to/repo --http 127.0.0.1:3411   # Streamable HTTP at /mcp
npx @codai/axiom-mcp --help                                # CLI verbs

--root は複数回指定できます。各ツールの root 引数は、いずれかのルートと一致するか、その配下にある必要があります。ルートが1つだけの場合は、それがデフォルトになります。環境変数や cwd へのフォールバックはありません（ERR_ROOT_REQUIRED / ERR_ROOT_NOT_ALLOWED）。

プロトコルリビジョン — --wire 2026|2025|2026-only

MCP TypeScript SDK v2（@modelcontextprotocol/server 2.0.0）を基盤としています。サーバーは、 2026-07-28 リビジョン（initialize なし、リクエストごとの _meta エンベロープ、server/discover、 リスト結果の ttlMs / cacheScope）と、同じエントリーポイントから2025年版のリビジョン（initialize ハンドシェイク、 HTTP セッション）の両方に対応しています。SDK は各 stdio 接続を、または各 HTTP リクエストを、クライアントが開始した時代のリビジョンに割り当てます。--wire 2026（デフォルト）と --wire 2025 はどちらも 両方のリビジョンに対応します。--wire 2026-only は、2025年版での開始を未対応のプロトコルバージョンエラーで拒否します。SDK v1 を使うクライアントは変更不要です。詳細：docs/reference/mcp-tools.md。

VS Code — .vscode/mcp.json

{
  "servers": {
    "axiom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@codai/axiom-mcp", "mcp", "--root", "${workspaceFolder}"]
    }
  }
}

Streamable HTTP — --http <host:port>

axiom mcp --root /abs/repo --http 127.0.0.1:3411            # loopback, no token needed
axiom mcp --root /abs/repo --http 0                          # random port; URL logged at info level
AXIOM_HTTP_TOKEN=$(openssl rand -hex 32) axiom mcp --root /abs/repo --http 0.0.0.0:3411 --log-level info

• エンドポイント：POST /mcp（2026-07-28 のリクエストはステートレスに処理されます。2025年版の initialize はセッションを開始して Mcp-Session-Id を返します。以降の2025年版リクエストでは、すべてこの ID を送信する必要があります）、GET /mcp （単独の SSE ストリーム。2025年版の各セッションにつき1つ）、DELETE /mcp（セッションを終了）、GET /health → { ok, name, version }（認証なし）。それ以外はすべて 404 の JSON になります。
• デフォルトではループバックです。 ループバック以外のホストでは、--http-token-env <NAME> で指定された環境変数（デフォルトは AXIOM_HTTP_TOKEN、16文字以上）にベアラートークンが設定されていないと、起動を拒否します。クライアントは Authorization: Bearer <token> を送信します。比較は定時間で行われます。ループバックではトークンは省略可能です。
• ループバックへのバインドでは DNS リバインディング保護が有効です（Host は <host>:<port>、localhost:<port>、 または 127.0.0.1:<port> である必要があります。それ以外は 403）。4 MiB を超えるリクエスト本文は 413 になります。
• 30分間アイドル状態の2025年版セッションは破棄されます。各セッション（および各2026年版リクエスト）には、1つのファクトリーから独自のサーバーインスタンスが割り当てられます（ルート、検出されたサブルート、ガード設定は共有されます）。トランスポートは dist/http-lazy.js にあり、--http の場合にのみ読み込まれます。また、プレーンな node:http を使用しており、ランタイムで express/hono は不要です。
• VS Code：{ "type": "http", "url": "http://127.0.0.1:3411/mcp" }。トークンを設定した場合は、 "headers": { "Authorization": "Bearer ${input:axiom-token}" } を追加します。

適合性：CI では packages/conformance がこのトランスポートに対して @modelcontextprotocol/conformance server を実行し、想定される失敗のベースライン（packages/conformance/baseline.yml）を使用します。

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "axiom": { "command": "npx", "args": ["-y", "@codai/axiom-mcp", "mcp", "--root", "/abs/path/to/repo"] }
  }
}

ツール

ツールセット（3.0、D-43）

axiom mcp はデフォルトでコアツールセットを提供します。ゲートを通して書き込むためにエージェントが必要とする6つのツールです：axiom_write、axiom_status、axiom_rollback、axiom_check、 axiom_apply、axiom_apply_dry_run。以下のプラン／マニフェスト／タスク関連の機能（core のマークがないすべての行）も公開するには、--tools full を指定してサーバーを起動してください。spec/tools.json と spec/codai-tools.json には、すべてのツールが "toolset": "core" | "full" として記載されています。ライブラリのユーザーは createServer(policy, { toolset: "full" }) / serverFactory(policy, { toolset }) を渡します。 parseToolset(value) はフラグの値を変換します（それ以外の場合は ERR_USAGE）。

ツール	リスク	入力	出力
axiom_plan_validate	READ	{ plan }	{ ok, planDigest?, errors[] }
axiom_plan_compile	ACT	{ plan, store?: inline|cas, root? }	ManifestBundle（root が指定されている場合、<root>/.axiom/ の下にのみ書き込みます — CAS blob と保存済みマニフェスト）
axiom_manifest_verify	READ	{ bundle, root? }	{ ok, manifestDigest, canonical, signed, missing[], errors[], signatures?: { trustFile, keyids[], findings[], ok, code? } } — signatures は root に .axiom/trust/keys.json がある場合のみ出力されます。ok でない場合の code は ERR_SIGNATURE_MISSING | ERR_SIGNATURE_INVALID です
axiom_check core	READ	{ bundle, profile?, root? }	CheckReport（verdict: pass|fail|error、preImage: verified|drifted|unverified）
axiom_check_start	READ	{ bundle, profile?, root? }	{ taskId, tool, status: "working", pollIntervalMs, ttlMs, elapsedMs } — axiom_check と同じ評価を、すぐに タスク として返します。これにより、時間のかかる guard.external スイート（ガードあたり最大15分）がクライアントの1回の呼び出しタイムアウトを超えて実行できます（S-406 / D-24）
axiom_task_get	READ	{ taskId }	completed になると result: CheckReport を含むディスクリプター、または failed／cancelled になると error: { code, message }。不明または期限切れの ID → ERR_TASK_NOT_FOUND
axiom_task_cancel	ACT	{ taskId }	ディスクリプター。実行中のガードツリーをすべて終了し、タスクは ERR_TASK_CANCELLED で cancelled になります（終端状態のタスクに対しては冪等）
axiom_plan_begin	ACT	Plan ヘッダー：{ name, intent, profile?, capabilities?, checks?, counter?, metadata? }	{ sessionId, artifacts: 0, bytes: 0, limits: { maxArtifacts, maxBytes }, ttlMs } — JSON が4 MiBの呼び出し上限を超える Plan 向けに、チャンク式の Plan セッションを開始します
axiom_plan_add	ACT	{ sessionId, artifacts[] }（各呼び出しは4 MiB以下）	セッションディスクリプター。チャンク間でパスが重複している場合 → ERR_INVALID_PLAN、上限（アーティファクト2000件／64 MiB）超過またはシール済みの場合 → ERR_PLAN_SESSION_STATE
axiom_plan_seal	ACT	{ sessionId, store?: inline|cas, root? }	ManifestBundle — axiom_plan_compile と同じコードパスでコンパイルされるため、ダイジェストは組み立てた Plan を一度にコンパイルした場合と一致します（プロパティテストで検証済み）。セッションは消費されます
axiom_apply_dry_run core	READ	{ bundle, root, profile? }	ApplyResult{mode:"dry-run", diff}
axiom_apply core	SENSITIVE	{ bundle, root, profile?, confirmDigest, mode?, branch?, commitMessage?, lockTimeoutMs? (0..600000), keepBackups? (0..1000) }	ApplyResult — ERR_CONFLICT の場合、error.details に { otherDigest, paths } が格納されます。ERR_LOCKED の場合は { holder, waitedMs, queuePosition } が格納されます
axiom_write core	SENSITIVE	{ root, files[]: { path, content?, encoding?: utf8|base64, op?: write|delete, mode? }, intent?, profile?, confirmDigest?, lockTimeoutMs?, keepBackups? }	1つのツールで書き込みます（2.5.0）：confirmDigest がない場合は status: "preview"（ドライラン＋チェック、diff、manifestDigest、next。.axiom/ の外部には何も変更されません）。同じファイルと confirmDigest を指定すると、axiom_apply と同様にアトミックに適用されます（ジャーナル、1ステップの axiom_rollback）。プレビュー後に対象が変更されている場合 → ERR_CONFIRM_DIGEST_MISMATCH。複数ファイルに対する変更や機微な変更にはこちらを推奨します
axiom_rollback core	SENSITIVE	{ root, manifestDigest }	{ status:"rolled-back", phase, steps }
axiom_manifest_diff	READ	{ a: bundle|"sha256:…", b }	{ added[], removed[], changed[] }
axiom_axm_parse	READ	{ source }（.axm テキスト）	{ plan?, diagnostics: [{ severity, code, message, range: { start: {line, column}, end } }] }
axiom_roots_list	READ	{}	{ roots: [{ path, writable, hasGit }] }
axiom_status core	READ	{ root? }	{ root, lock: { held, holder?: { pid, host?, digest?, since?, stale }, queue[], intents[] }, interrupted[], corrupt[], lastApplied?, chain: { ok, entries, head, firstBad?, missingJournals } } — axiom status --json と同じです。ロックは取得しません
axiom_repo_snapshot	READ	{ root?, include?[], exclude?[], maxFiles? (20000, cap 50000), maxBytes? (64 MiB), respectGitignore? (true), withContentDigest? (true) }	RepoSnapshot { snapshotDigest, body: { files: [{ path, bytes, sha256?, mode, kind }], truncated, counts } } — ソート済みで、タイムスタンプや絶対パスは含みません。.git/ と .axiom/ は常にスキップされます。シンボリックリンクは記録されますが、たどりません（docs/guides/snapshot.md）
すべてのツールには、MCP の annotations（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）と outputSchema があります。structuredContent は結果全体を、content[0].text は簡潔な要約（ダイジェスト、判定、件数、最初の 20 件の検出結果）を返します。エラーは閉じた ERROR_CODES 列挙型に基づく { code, message, path? } とともに isError: true で返されます。ハンドラーが例外をスローすることはありません。spec/tools.json は同じレジストリから生成され（pnpm build:spec）、パリティテストで整合性が確認されます。spec/codai-tools.json は codai の packages/agent-core/spec/tools-v2.json のエントリー形式（{ name, risk, toolset, description, parameters }）にした同じレジストリです。詳しくは docs/integration/codai.md を参照してください。

リソース：axiom://manifest/{sha}、axiom://report/{sha}、axiom://applied/{sha}、axiom://profile/{name}、axiom://schema/{Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot}、axiom://emitters（--emitter <pkg> で読み込まれるテンプレートエミッター。3.0 以降はデフォルトで空です。@codai/axiom-emitters-web をリポジトリの隣にインストールして --emitter @codai/axiom-emitters-web を渡してください。詳しくは docs/guides/emitters.md を参照してください）、axiom://lock（許可リストに登録されたすべてのルートについての { roots: [{ root, held, holder?, queue[], intents[] }] }。読み取り専用）。

信頼モデル

• 起動時にルートを realpath 化し、ディレクトリであることを確認したうえで、その集合を固定します。要求されたルートも realpath 化されます（Windows では大文字小文字を区別せず包含関係を確認します）。範囲外のものはすべて重大なエラーになります。
• axiom_apply には confirmDigest === bundle.manifestDigest が必要です。dry-run で確認したダイジェストをそのまま返してください。 適用前チェックはプロファイル（デフォルトは default、または <root>/.axiom/profiles/<name>.json）に対して実行されます。判定が pass 以外の場合、書き込み前に ERR_CHECKS_FAILED で中止されます。
• 4 MiB を超えるペイロードは、処理開始前に拒否されます（ERR_BUNDLE_TOO_LARGE）。
• タスクとプランセッションはサーバーのプロセス内に保持されます（そのプロセスが処理するすべての接続／リクエストで共有され、ディスクには保存されません）。再起動すると消去されます。完了したタスクは 10 分間ポーリング可能で、アイドル状態のセッションは 30 分後に期限切れになります。同時実行できるタスクは最大 8 件です（超過すると ERR_EBUSY）。サーバーを停止すると、実行中のすべてのタスクが中止され、ガードのプロセスツリーが強制終了されます。
• .axiom/lock により、ルートごとの apply は単一ライターに制限されます。ジャーナルにより、クラッシュ時の安全性と取り消しが保証されます。
• stdout には JSON-RPC のみが出力されます。ログは stderr に JSON 行形式で出力されます（--log-level error|warn|info|debug、デフォルトは warn）。
• 外部ガード（guard.external）は、プロセスの起動時に --allow-guards が指定され、かつプロファイルで facts.allowGuards: true に設定されていない限り、無効です。相対パスのコマンドは <root>/scripts/ 配下に置く必要があります。絶対パスのコマンドは --guard-allowlist <abs> で正確に指定する必要があります（複数回指定可能）。ガードは引数配列（シェルは使用しません）、環境変数を除去した環境、実時間のタイムアウトを使って起動され、GuardOutput JSON を出力する必要があります。詳しくは docs/guides/checks.md を参照してください。
• 署名付きマニフェスト（docs/guides/signing.md）：ルートでは .axiom/trust/keys.json に Ed25519 公開鍵をピン留めできます。プロファイルで manifest.requireSigned を設定すると、署名されていないバンドル、改ざんされたバンドル、信頼されていないバンドルが拒否されます。また、antiRollback: true にすると、counter ≤ .axiom/trust/state.json#lastCounter の場合も拒否されます。axiom_apply は status: "applied" の場合にのみ、その状態を更新します。秘密鍵がサーバーに渡ることはありません。署名には AXIOM_SIGNING_KEY または --key-file を使って axiom sign を実行します。

CLI

axiom mcp     [--root <abs>]... [--allow-guards] [--guard-allowlist <abs>]... [--log-level warn]
              [--http <host:port>] [--http-token-env AXIOM_HTTP_TOKEN] [--require-human]
axiom init    [--root .] [--harness auto|copilot|claude|codex|vscode|cursor|windsurf|gemini|junie|cline] [--daemon]
              [--profile-name <name>] [--force] [--upgrade] [--managed --out <dir>] [--json]
              (.vscode/mcp.json + Pre/PostToolUse hooks + .axiom/profiles/<name>.json + .axiom/gate-profile.json + .gitignore; idempotent)
axiom doctor  [--root .] [--json]               (exit 0 = no failing check, 2 = at least one fail; warnings exit 0)
axiom stats   [--root .] [--since 7d] [--json]  (gate decisions, p50/p95, per harness; silent-gate alarms)
axiom undo    --session <agent> [--root .] [--dry-run] [--force] [--since <iso>]   (restore one session's writes; exit 1 = conflicts)
axiom import-guard <guard.ps1> [-o profile.json]   (PowerShell guard tables → gate profile "commands")
axiom status  [--root .] [--json]               (lock holder/queue/intents, interrupted journals, last applied, chain)
axiom log     [--root .] [--limit 20] [--json]  (journal chain, newest first)
axiom compile <plan.json|plan.yaml|plan.axm> [-o out.json] [--store cas --root .] [--allow-net [--net-allow host[,host]]] [--allow-file]
axiom verify  <bundle.json> [--root .]          (--root: also verify signatures against .axiom/trust/keys.json)
axiom verify  --journal --root .                (journal hash chain; broken → exit 1 + code ERR_JOURNAL_CHAIN)
axiom verify  <bundle.json> --tree <root> [--pre] [--attest out.intoto.json]   (tree matches manifest? docs/guides/verify-tree.md)
axiom check   <bundle.json> --root . [--profile p] [--json | --format text|json|sarif] [--allow-guards] [--guard-allowlist <abs>]...
axiom apply   <bundle.json> --root . [--dry-run] [--profile p] [--confirm <digest>] [--lock-timeout <ms>] [--keep-backups <n>]
              [--pr [--branch b] [--message m]] [--allow-guards] [--guard-allowlist <abs>]...
axiom rollback <digest> --root .
axiom gc      --root . [--dry-run] [--older-than 30d] [--keep all-manifests|journal] [--undo-ttl 7d]   (CAS garbage collection; CLI only, no MCP tool)
axiom diff    <a.json> <b.json>
axiom schema  <Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot>
axiom emitters [--json]
axiom keygen  [--out <dir>] [--name <label>]     (ed25519; private key → <dir>/axiom-signing-<id>.key 0600, public entry → stdout)
axiom sign    <bundle.json> [--key-file <path>] [-o out.json] [--root-id <id>]   (key from --key-file or $AXIOM_SIGNING_KEY; --root-id = root-bound envelope)
axiom sign    <bundle.json> --keyless [--bound --root . | --root-id <id>] [-o out.json]
              (Sigstore via ambient OIDC → bundle.keylessSignatures; no OIDC → exit 1 ERR_KEYLESS_UNAVAILABLE)
axiom trust   add <pub.json> --root . | remove <keyid> --root . | list --root . | root-id [<id>|--clear] --root .
axiom gate    --stdin [--post] [--format <harness>] [--root <dir>] [--profile <file>] [--fail-open] [--no-shell-scan] [--no-root-discovery]
              [--track-reads] [--deny-exit 0|2] [--log-level warn]
axiom serve   --hook --root <abs>... [--host 127.0.0.1] [--port 47861] [--token-env <NAME>] [--otel]
axiom migrate v1 <manifest.json> [-o plan.json] [--profile default] [--cas <root>] [--content <dir>] [--overwrite]
                                               (v1 manifest → v2 Plan, lazy chunk; exit 1 = migrated with warnings — docs/guides/migrate.md)
axiom snapshot --root . [-o snap.json] [--include <glob>]... [--exclude <glob>]... [--max-files n] [--max-bytes n] [--no-gitignore] [--no-digest]
axiom snapshot-diff <a.json> <b.json>          (RepoSnapshot → { added, removed, changed })

終了コード：0 成功 · 1 判定失敗／適用失敗／ジャーナルチェーンの破損／キーなしでは利用不可 · 2 使用方法またはエラー （doctor：2 = チェック失敗）。mcp 以外の動詞は、JSON を標準出力に出力します（init、doctor、status、log、check、emitters は、--json を指定しない場合は人間が読める形式で出力します）。

ref ソース（{ type: "ref", uri, digest }）は、デフォルトでオフラインです。ダイジェストがすでに <root>/.axiom/cas にある場合はネットワークを使わずに解決され、それ以外の場合は ERR_NET_DISABLED になります。--allow-net を指定すると、https: のみを取得します（リダイレクトなし、タイムアウト 30 秒、上限 32 MiB）。必要に応じて、 --net-allow でホストを制限できます（*.example.com のワイルドカード）。ピン留めされたダイジェストを検証し、ブロブを CAS に保存します。不一致の場合は何も保存されません（ERR_DIGEST_MISMATCH）。apply は取得を行いません。MCP の axiom_plan_compile ツールにはネットワーク切り替えオプションがありません。docs/reference/plan-format.md および docs/concepts/cas.md を参照してください。

フックモード — axiom gate --stdin

Claude Code、Copilot CLI、VS Code エージェントのフック用の PreToolUse フックです。標準入力からハーネスのペイロードを1つ読み込み（{tool_name, tool_input, cwd} と {toolName, toolArgs, cwd} の両方の形式に対応し、toolArgs は JSON 文字列の場合があります）、Write|Edit|MultiEdit|NotebookEdit、create_file|replace_string_in_file|insert_edit_into_file|apply_patch|multi_replace_string_in_file|edit_notebook_file、および汎用の write|edit の書き込み先を抽出します。シェルツール（Bash、run_in_terminal など）については、書き込みプリミティブ（>、>>、tee、rm、mv、cp、sed -i、git checkout|reset|clean、PowerShell の Set-Content／Remove-Item など）をスキャンします（ヒューリスティックについては docs/getting-started/hooks.md に記載）。そして高速な述語のみを実行します。すなわち、包含性と RelPath ルール（..、CON、NTFS ADS → ERR_CONTAINMENT／ERR_PATH_*）、path.deny、path.allow、content.noSecrets、およびペイロードに新しいコンテンツが含まれる場合の content.maxBytes です。フェイルクローズ（D-18）：応答が得られない場合は拒否します。

結果	終了コード	標準出力	標準エラー
許可／書き込み以外、シェル以外のツール	0	—	—
拒否	0（--deny-exit 2 の場合は 2）	1つのオブジェクト：hookSpecificOutput{…}（Claude）＋フラットな permissionDecision／permissionDecisionReason（Copilot）＋axiom{verdict, code, path, toolClass, standard:"owasp-acs/0.1"}	AXIOM GATE DENY <code>: <reason> (<relpath>)
認識可能なパスキーがない書き込みツール	拒否時と同様	拒否 JSON	AXIOM GATE DENY ERR_UNSUPPORTED_OP: …
不正なペイロード、標準入力のタイムアウト（2 s）、内部エラー	拒否時と同様（フェイルクローズ）	拒否 JSON	AXIOM GATE DENY ERR_INTERNAL: … (fail-closed; pass --fail-open to allow)
同上、--fail-open 指定時	0	—	AXIOM GATE WARN: … — failing open (--fail-open)

拒否時に終了コードが 0 になるのは 2.4.1 以降です（D-35）。Windows では npm の axiom.ps1 シムが 2 を 1 に書き換え、VS Code は 1 を警告として扱うためです。JSON 対応の各ハーネスは終了コード 0 でもドキュメントの内容に従います。終了コードのみを使うハーネス（Windsurf）では --deny-exit 2 を使用してください。読み取り専用ツールには、ゲートのチャンクが読み込まれる前に応答します。同じリポジトリの兄弟ワークツリー内にあるターゲット（git common dir が同一）は、ERR_CONTAINMENT ではなく、そのワークツリーのルートとゲートプロファイルに基づいて判定されます。

ルート = ペイロードの cwd を起点に、最も近い .git／リポジトリの .axiom/ の祖先まで上にたどった場所（ホームディレクトリには到達しません。--no-root-discovery で無効化できます）。見つからない場合は --root、それもなければプロセスの cwd です（cwd を使用してよいのはフックだけです。ハーネスはプロジェクトディレクトリでフックを起動し、その値を管理するためです）。相対ターゲットは cwd を基準とします。 プロファイル = --profile <file> → <root>/.axiom/gate-profile.json → ~/.axiom/gate-profile.json → 組み込みの { deny: [".git/**", ".axiom/**", "**/*.lock", "pnpm-lock.yaml", ".env", ".env.*", "**/node_modules/**"], noSecrets: true, pii: false }。 スキーマ：{ deny: string[], allow?: string[], noSecrets: boolean, pii: boolean, maxBytes?: number }（厳密）。 pii: true の場合は個人データ（cnp、email、phoneRo、card）もスキャンします。S-414 以降、デフォルトでは無効です（pyproject.toml のメンテナーのメールアドレスにより実際の編集が拒否されたためです。docs/guides/checks.md を参照）。

gate は独立した遅延読み込みチャンクです（dist/gate-lazy.js、MCP SDK なし）。プロセス内のペイロードあたりの p95 は約 5 ms、Node.js の起動を含むエンドツーエンドの所要時間は約 150–200 ms です。check-gate-latency は p95 ≤ 250 ms を保証します。 各ハーネスの設定方法については docs/getting-started/hooks.md を参照してください。