Skip to content

MCP tools and resources

Reference for protocolith mcp. For setup and an example session see Use Protocolith from an AI agent.

Transport: newline-delimited JSON-RPC 2.0 on stdio. Methods: initialize, ping, tools/list, tools/call, resources/list, resources/read. The server answers with the protocol version the client asks for if it knows it (2025-06-18, 2025-03-26, 2024-11-05), otherwise the newest. Notifications get no answer. Unknown methods return -32601; malformed input -32700 or -32600.

Tools

Arguments not listed are rejected (additionalProperties is false). A result is one text content item holding canonical JSON. isError is true when the operation was rejected or the ledger does not verify; the JSON then carries ok: false, codes, error (with a hint where there is one) and violations, exactly as with --json.

Tool Arguments Same as
protocolith_summary optional protocol protocolith summary: verdict, head, counts, per-protocol table, problems. Start here.
protocolith_log optional protocol, type, status, tail protocolith log plus the head
protocolith_show seq (integer, at least 0) protocolith show
protocolith_schema optional name (freeze, record, deviation, issue, entry, all) protocolith schema
protocolith_capture optional files (paths inside the working directory), env protocolith capture
protocolith_atlas optional out, title, cards (directories), i18n, default_lang, max_rows protocolith atlas; returns the path written
protocolith_freeze protocol (object), optional supersedes protocolith freeze
protocolith_record body (object) protocolith record
protocolith_deviation body (object) protocolith deviation
protocolith_verify optional expect_head (SEQ:HASH) protocolith verify-ledger
protocolith_issue seq (integer, at least 0) protocolith issue

protocolith_issue writes cards inside the store (<store>/cards); there is no output directory argument. protocolith_capture refuses paths that leave the server's working directory (BAD_PATH), runs nothing and reads no environment values. Only the freeze, record, deviation and issue tools write to the store. protocolith_atlas writes one HTML page and nothing else: out (default protocolith-atlas.html), cards and i18n must stay inside the working directory (BAD_PATH). Without cards it uses the server's ledger; isError is true when the ledger does not verify (the page is still written, with a warning banner).

Resources

Read-only, mimeType application/json.

URI Content
protocolith://summary the same object as protocolith_summary
protocolith://ledger {"entries": [...], "head": {...}}
protocolith://schema/freeze JSON Schema of the protocol object
protocolith://schema/record JSON Schema of a record body
protocolith://schema/deviation JSON Schema of a deviation body
protocolith://schema/issue JSON Schema of the issue input
protocolith://schema/entry JSON Schema of a ledger line, with the stored body of each type in $defs

An unknown URI is JSON-RPC error -32002. A ledger problem such as NO_LEDGER is -32000 with the code at the start of the message. The schemas are generated from the verifier's field rules; the verifier stays authoritative.

The normative text is section 5 of the core specification.