# The MCP server (memprove mcp)

`memprove mcp serve` is a Model Context Protocol server on standard input and output. The client starts it (the
entry `init` writes), and an agent reads and writes the ledger through its ten tools: `pack`, `claims`, `context`,
`tasks`, and `ledger_verify` read; `begin`, `checkpoint`, `decide`, `end`, and `complete` write. Parameters are
numbers and labels, never a UUID. No tool runs a command; tests are recorded with `memprove run` in a shell, and
their labels are then cited through the tools. Both protocol eras are served, decided per request: the 2026-07-28
revision (`server/discover`, the protocol version in each request's `_meta`) and the `initialize` handshake of
2025-11-25 and 2025-06-18. Standard output carries protocol messages only; standard error carries one line per message
and never a token or an argument value.

| tool | kind | daemon operations | token scope |
|---|---|---|---|
| `pack` | read | `getTaskCapsule`, `listTasks` | mcp-read |
| `claims` | read | `getTaskCapsule`, `listTasks` | mcp-read |
| `context` | read | none (local files only) | none |
| `tasks` | read | `listTasks` | mcp-read |
| `ledger_verify` | read | `verifyLedger` | mcp-read |
| `begin` | write | `listSessions`, `resolveWorkspace`, `createTask`, `listTasks`, `createSession`, `transitionTask` | mcp-write |
| `checkpoint` | write | `getTaskCapsule`, `createCheckpoint`, `listTasks`, `listSessions` | mcp-write |
| `decide` | write | `getTaskCapsule`, `proposeDecision`, `listTasks`, `listSessions` | mcp-write |
| `end` | write | `endSession`, `getTaskCapsule`, `listSessions`, `listTasks` | mcp-write |
| `complete` | write | `transitionTask`, `getTaskCapsule`, `listTasks`, `listSessions` | mcp-write |

- `pack` returns the Pack as `resume --pack` prints it, byte for byte, after an opening statement like the hook's (the
  Task, the current UTC time, the server's agent, the open-item sentence); The `pack` tool's default budget is 6000
  UTF-16 code units; `query` selects as `--query` does, `manifest` adds nothing since U16. `claims` gives the full
  lines of named claims. `begin` takes `task` (a number from `tasks`) or `new_task`, and `agent_name`, `agent_role`,
  `parent_session` (else the server's environment, else its context); its result names the Session's agent.
  `checkpoint` takes facts, open items, reaffirmations, withdrawals and the next action with labels (`r1`) and claim
  numbers; `decide` a Decision; `end` ends the context's Session, or with `abandoned` the Session a number names;
  `complete` completes the Task on the context's passed runs. Every result's object begins with `task_id` and
  `session_id`. An error result's text begins with the Problem code (`role_forbidden: …`) and a fixed sentence.
- `memprove mcp print-config` prints it and writes nothing: the entry belongs in `<Workspace root>/.mcp.json`
  (project scope) or in `~/.claude.json` (local or user scope). The entry names the executable, the arguments `mcp
  serve --config-dir <config>` and `env.MEMPROVE_CONFIG_DIR`, no data directory, no token: A token never goes into
  `.mcp.json`. Every tool call reads the token and the data directory anew: the token from `MEMPROVE_TOKEN`, else
  the file named by `MEMPROVE_TOKEN_FILE`, else `<configuration directory>/token`; the data directory from
  `MEMPROVE_DATA_DIR`, else the one line of `<configuration directory>/data-dir`. A rotated or revoked token takes
  effect on the next call.
- The read tools need `mcp-read`; the writes need `mcp-write`. The write tools also send reads, which need `mcp-read`:
  `begin` lists Sessions and Tasks, `checkpoint` and `decide` read the Capsule to resolve numbers. The agent token
  carries both scopes.
- The Workspace is the one of `CLAUDE_PROJECT_DIR`, else of the server's working directory (the MCP server works in
  the Workspace of `CLAUDE_PROJECT_DIR`, which Claude Code sets to the project root, else of its working directory).
  Nothing is kept between calls: every call reads the context files on disk again, so a `memprove run` in the shell
  and a `checkpoint` through the tool see each other.