AXIOM

@codai/axiom-mcp

MCP server (stdio or Streamable HTTP) and CLI for AXIOM v2 — the transactional write gate for coding agents: Plan → canonical ManifestBundle → set-level checks → hash-gated two-phase apply → journal. dist/cli.js (thin entry) + dist/cli-main.js (lazy-loaded engines; the MCP SDK v2 and zod are bundled into the mcp-lazy / http-lazy chunks); no runtime dependencies.

Install & run

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 may repeat. Every tool root argument must equal or lie inside one of them; with exactly one root it is the default. There is no env-var or cwd fallback (ERR_ROOT_REQUIRED / ERR_ROOT_NOT_ALLOWED).

Protocol revisions — --wire 2026|2025|2026-only

Built on MCP TypeScript SDK v2 (@modelcontextprotocol/server 2.0.0). The server speaks the 2026-07-28 revision (no initialize, per-request _meta envelope, server/discover, ttlMs/cacheScope on list results) and the 2025-era revisions (initialize handshake, HTTP sessions) from the same entry — the SDK pins each stdio connection, or routes each HTTP request, to the era the client opened with. --wire 2026 (default) and --wire 2025 both serve both; --wire 2026-only refuses 2025 openings with the unsupported-protocol-version error. Clients on SDK v1 need no change. Details: 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

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

• Endpoints: POST /mcp (2026-07-28 requests are served statelessly; a 2025 initialize opens a session and returns Mcp-Session-Id, which every later 2025 request must send), GET /mcp (standalone SSE stream, one per 2025 session), DELETE /mcp (close the session), GET /health → { ok, name, version } (unauthenticated). Anything else is 404 JSON.
• Loopback by default. A non-loopback host refuses to start unless a bearer token is present in the env var named by --http-token-env (default AXIOM_HTTP_TOKEN, ≥ 16 chars). Clients send Authorization: Bearer ; the compare is constant-time. A token is optional on loopback.
• DNS-rebinding protection is on for loopback binds (Host must be : , localhost: or 127.0.0.1: ; otherwise 403). Request bodies over 4 MiB are 413.
• 2025 sessions idle for 30 minutes are evicted; each session (and each 2026 request) has its own server instance from one factory (roots, discovered sub-roots and guard settings are shared). The transport lives in dist/http-lazy.js, loaded only with --http, and is plain node:http — no express/hono at runtime.
• VS Code: { "type": "http", "url": "http://127.0.0.1:3411/mcp" }; add "headers": { "Authorization": "Bearer ${input:axiom-token}" } when a token is set.

Conformance: packages/conformance runs @modelcontextprotocol/conformance server against this transport in CI with an expected-failures baseline (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"] } } }

Tools

Toolsets (3.0, D-43)

axiom mcp serves the core toolset by default — the six tools an agent needs to write through the gate: axiom_write, axiom_status, axiom_rollback, axiom_check, axiom_apply, axiom_apply_dry_run. Start the server with --tools full to also expose the plan / manifest / task plumbing below (every row not marked core). spec/tools.json and spec/codai-tools.json list every tool with "toolset": "core" | "full". Library users pass createServer(policy, { toolset: "full" }) / serverFactory(policy, { toolset }); parseToolset(value) maps the flag value (ERR_USAGE otherwise).

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and an outputSchema; structuredContent is the full result, content[0].text a small summary (digest, verdict, counts, first 20 findings). Errors come back as isError: true with { code, message, path? } from the closed ERROR_CODES enum — a handler never throws. spec/tools.json is generated from the same registry (pnpm build:spec) and guarded by a parity test. spec/codai-tools.json is the same registry in codai's packages/agent-core/spec/tools-v2.json entry shape ({ name, risk, toolset, description, parameters }) — see docs/integration/codai.md.

Resources: axiom://manifest/{sha}, axiom://report/{sha}, axiom://applied/{sha}, axiom://profile/{name}, axiom://schema/{Plan|Manifest|ManifestBundle|CheckReport|ApplyResult|Profile|Journal|RepoSnapshot}, axiom://emitters (template emitters loaded with --emitter — empty by default since 3.0; install @codai/axiom-emitters-web next to the repo and pass --emitter @codai/axiom-emitters-web, see docs/guides/emitters.md), axiom://lock ({ roots: [{ root, held, holder?, queue[], intents[] }] } for every allowlisted root; read-only).

Trust model

• Roots are realpath'd at startup, must be directories, and the set is frozen. Requested roots are realpath'd too (case-insensitive containment on Windows); anything outside is a hard error.
• axiom_apply requires confirmDigest === bundle.manifestDigest — echo the digest you saw in dry-run. Pre-apply checks run against the profile (default default, or /.axiom/profiles/ .json); a non-pass verdict aborts with ERR_CHECKS_FAILED before any write.
• Payloads over 4 MiB are rejected up front (ERR_BUNDLE_TOO_LARGE).
• Tasks and plan sessions live in the server process (shared by every connection/request the process serves; never on disk). A restart forgets them; finished tasks stay pollable for 10 min, idle sessions expire after 30 min; at most 8 tasks run concurrently (ERR_EBUSY beyond that). Stopping the server aborts every running task and kills its guard trees.
• .axiom/lock makes apply single-writer per root; the journal makes it crash-safe and reversible.
• stdout carries only JSON-RPC. Logs are JSON lines on stderr (--log-level error|warn|info|debug, default warn).
• External guards (guard.external) are off unless the process is started with --allow-guards *and* the profile sets facts.allowGuards: true. Relative commands must live under /scripts/; absolute ones must be listed exactly via --guard-allowlist (repeatable). Guards are spawned with an args array (never a shell), a scrubbed environment, a wall-clock timeout, and must print GuardOutput JSON — see docs/guides/checks.md.
• Signed manifests (docs/guides/signing.md): a root can pin Ed25519 public keys in .axiom/trust/keys.json; a profil