MCP stdio server

artifactize mcp serves the verification and non-interactive inspection tools in the same binary as the CLI. Register it in the coding host, starting from the project directory; see registration below. --repo PATH selects a different project and --state-dir PATH selects its state. The server resolves these once at startup. Run/request/session reads stay bound to that repository; cache records are reusable across repositories in the state.

It works with current MCP hosts and with older ones. The host talks to it only through the program’s input and output: stdout carries protocol messages, and diagnostics go to stderr. There is no network port or extra token. A bounded verify_watch call can also send standard MCP progress notifications. See Protocol versions for the details.

Register the MCP server

MCP (Model Context Protocol) connects your coding assistant to artifactize’s tools, so it can inspect the project and start or observe reviews. Stdio means the host launches artifactize mcp and exchanges messages through that program’s standard input and output, rather than connecting to a network port.

Complete the installation setup, then launch the coding host from your project directory. The stdio server uses the same binary and shared state as the CLI. It binds to one repository/state when started; it is not the HTTP review store (artifactize server), and requires no port, token argument or changed host timeout.

In Claude Code and Codex, the plugin registers this server together with the Hey Arti skill; the commands below are the manual registration. They configure the host explicitly; artifactize does not install or change host configuration for you. Follow the host’s normal trust/approval flow.

Claude Code

From the project directory:

claude mcp add --transport stdio --scope project artifactize -- artifactize mcp
claude mcp get artifactize

Project registration creates the host’s project .mcp.json. Keep it free of credentials and machine-specific paths if you share it. Start/restart Claude Code from this project, use its MCP view to confirm the server is connected, and check that the verification and inspection tools below are listed.

Codex CLI

Register the stdio command, then start Codex in the project directory:

codex mcp add artifactize -- artifactize mcp
codex mcp get artifactize

Codex records this in its own MCP configuration. A globally registered command still needs to start from the intended project directory. Where a host cannot launch in the project, register a project-specific command using artifactize --repo PATH mcp rather than pointing it at the skill directory. Normal host permissions/authentication still apply; no bypass flags are needed.

Registration supplies tools, not the Hey Arti skill.

Verification tools

scope is the shared Selection JSON envelope, tagged by kind:

{"kind":"all"}

Other forms are {"kind":"artifact","artifactId":"library"}, {"kind":"eval","evalId":"library/tests"}, {"kind":"artifacts","artifactIds":["library","consumer"]} and {"kind":"evals","evalIds":["library/tests","consumer/review"]}. Array selections contain 1–64 IDs, preserving first-occurrence order. Normal CLI dependency/reuse defaults apply; there are no transport-specific scheduling or lifecycle settings. This envelope is not a CLI selection file: --evals-file and --artifacts-file accept JSON arrays of IDs or one ID per line, without a kind tag.

A request_key is 1–128 ASCII letters/digits/._:-. Same repository + same key returns the same attempt, even after edits or completion. A new attempt needs a new key or no key. Omitting the key always creates a new Run while retaining normal eval-result reuse.

Concurrency is unlimited by default: all READY evals can start, subject to backend limits in limits.json. An optional positive integer jobs is the same per-Run cap as CLI --jobs; add it only when unrestricted concurrency causes trouble. The Run omits jobs when unlimited; older saved numeric caps remain readable.

Both mode arguments default false and pass directly to shared RunModes. speculate starts requested downstream work within core scheduling limits before upstream judgment; an upstream RED/ERROR cancels only the work it makes invalid. defer_human permits provisional progress and returns terminal signoffs_pending when only deferred sign-offs remain. verify_result reports verdict SIGNOFFS_PENDING; this is not full approval (the CLI watcher exits 5). Explicit gate = "blocking" still blocks. DEFERRED and PROVISIONAL request states are forwarded from core, not reinterpreted by MCP. Later sign-offs do not re-run the machine work.

A running answer is smaller than 2 KiB. Waiting is ordinary state, not an error. verify_wait treats runtime, Agent and Human evals equally: it does not return early merely because a person is needed. next_check is observation advice, not a request to poll rapidly or keep a model context warm.

Artifactize owns the Run. Dropping a request, closing the MCP connection, stopping a watcher or ending an agent turn never cancels it. Only verify_cancel does. RED/INCOMPLETE/ERROR/cancelled are saved Run outcomes, not malformed tool calls. Human judgment stays with the person; MCP cannot claim, release or submit it.

Inspection tools

All inspection tools accept an optional detail cursor as well as the arguments listed below. They invoke the same core operations and JSON projections as their CLI counterpart; MCP adds only a bounded, lossless transport page.

session_show.reference accepts a saved session reference, request ID or session ID, with the same producer/state checks as the CLI. A missing cache record is JSON null (or an empty array for history), just as in CLI JSON output. Static tools_check never invokes project tools or starts sessions. status may run trusted fingerprint commands and consult the configured review store; declared commands are not an OS sandbox. MCP exposes no login/logout actions and never returns credentials. models, doctor and remote_status may check backend readiness. Codex model listing can renew artifactize-owned tokens or remove the stored sign-in after a terminal refresh rejection, just as the CLI does.

Detail pages

A detail page contains at most one text entry and is smaller than 64 KiB including the structured answer and legacy text mirror. The entry is a UTF-8 fragment of the exact CLI JSON, not a clipped preview or a second result schema:

{"encoding":"json","entries":[{"offset":0,"text":"{\"ok\":true,\"artifacts\":3,\"evals\":4}"}],"next_cursor":null}

Concatenate entries[].text in order until next_cursor is null, then parse the joined text as JSON. Serialization is compact; CLI pretty-print whitespace is not preserved. Reinvoke the same tool with the same arguments, adding cursor from the previous page. Offsets are UTF-8 byte offsets. run_list.offset selects the next group of Run records; it is distinct from the cursor continuing one group’s JSON. verify_result instead pages its structured findings array.

Cursors identify the tool, arguments and current saved projection. Elapsed fields use the first page’s observation clock, so clock movement alone cannot expire a continuation while a Run waits for a person. A foreign or stale cursor is rejected; restart that inspection if the evidence changed. No transport-owned snapshots or background subscriptions are stored. Tool operation failures use MCP isError:true with bounded {code,message} content (the existing core operation errors retain their message under operation_failed); details are not truncated to pretend that an incomplete page is the whole result.

Deliberately absent

No credential login/logout, Human claim/submit/release, prune, cache removal, remote push, interactive monitor/review, store server, project-tool execution or Agent-session follow-ups. The CLI and normal Human review interfaces remain the entry points for these actions.

Streaming and focused diagnosis

Submit with verify_start, retain the Run ID, then call verify_watch with the standard tool-call metadata {"progressToken":"your-observer"} in _meta. While this call is pending, artifactize subscribes to shared state changes and sends notifications/progress. The notification’s message is a JSON envelope:

• {"kind":"update","data":...}: compact live state/counts, not approval.
• {"kind":"eval_result","data":...}: one saved request/eval status and concise summary, including reused and provisional results, not the Run verdict.
• {"kind":"outcome","data":...}: final Run validation, using verify_result’s schema. Follow its next_cursor through verify_result for remaining findings.

Each attachment replays its baseline and already completed evals; deduplicate across attachments by request ID and status if needed. A terminal observation returned at a bound does not guarantee that the client received an outcome notification; use verify_result for authoritative final validation. Without a progress token, the same call waits but sends no notifications; prefer verify_wait in clients that do not consume progress. No rapid polling is needed. Subscriptions end with the call (30-second bound), client cancellation or connection closure, and a later call reattaches to the saved Run (see Verification tools for who owns the Run). Lost/coalesced invalidations reconcile from saved state rather than inventing a complete event history.

The client/agent host must display progress or route it into its own task queue/conversation. MCP notifications do not themselves create model turns, keep inference caches alive, or deliver after the call/connection ends. Artifactize cannot inject messages into an arbitrary host. For a shell-capable host, artifactize verify --all --watch or artifactize run watch RUN streams the same JSON-line events until terminal; the host can supervise that process and route its output. These are implemented transports, not a claim that every coding host supports live conversation delivery.

From a failed finding, use its request ID with request_logs, not run_show’s entire audit. stream defaults to both. Without a range, the last 50 matching lines are returned; tail selects 1–200 matching lines. start/end are inclusive one-based original line numbers and exclude tail. search is a case-sensitive literal (1–2048 UTF-8 bytes), applied before the tail selection. Forward queries are bounded to 200 lines and a byte budget per stream; next_start continues the query with the same stream/search/end. Lines longer than 2048 raw bytes are explicitly clipped with bounded head/tail text; the full local bytes remain on disk. A search can match past the displayed head/tail of a clipped line. Results are cleaned UTF-8 diagnostic text, not a byte-for-byte export. Normal detail paging still wraps the bounded answer.

Each stream’s evidence says complete (full local capture, including the tail), partial (no confirmed EOF, such as active/interrupted capture), saved_audit (older/remote/pruned local capture; possibly only the first 128 KiB), missing, or not_runtime (use request/session evidence instead). Empty is not missing. A reused request follows its original local producer; remote records do not promise locally retained logs. Full raw stdout/stderr belong to the Run output, not SQLite/remote result JSON, and disappear with normal output pruning. The 128 KiB cleaned per-stream audit remains compatible and bounded; pagination cannot recover a tail when only that old/truncated audit survives.

config_graph discovers static definitions, evals, cycle peers and input-to-consumer relations without invoking hooks. Select an Artifact/eval for its required closure; add impact:true to include reachable downstream consumers and their required inputs. This is conservative structural reachability, not proof that every included eval’s reuse key changed. Use status to inspect actual reuse decisions.

Protocol versions

The server uses the pinned rmcp transport. It supports the 2026-07-28 MCP lifecycle, with discovery and per-request metadata, and older clients that start with initialize and notifications/initialized. It offers no Tasks extension and no durable subscription owned by the transport.