Chief over MCP

Chief speaks the Model Context Protocol on stdio. Any harness that speaks MCP can read and write the memory.

For a skill-capable agent with shell access, including Codex and Claude Code, prefer the Chief skill plus the chief CLI; the native skill installer sets that up for Codex and Claude Code. It loads the operating guidance only when relevant and lets the agent inspect just the commands it needs. MCP is the compatibility path for harnesses without shell access or workflows that explicitly prefer typed MCP tools. The MCP server serves the same skill contract as its initialize instructions.

chief mcp

That is the whole server. It reads the credential chief login left on this machine, so there is no separate API key and nothing to configure per harness.

Skill plus CLI (preferred)

Install the bundled Chief skill for Codex and Claude Code:

chief skill --install

Start a new agent session after installation. No repository checkout or GitHub access is required. Use --target codex or --target claude-code to choose one.

MCP compatibility

If a harness cannot use the skill-plus-CLI path, or you explicitly want Chief as a set of MCP tools, configure the server directly.

Claude Code

claude mcp add chief -- chief mcp

Codex CLI and ChatGPT desktop (MCP only)

Codex uses TOML, not the JSON below, and ChatGPT desktop reads the same file — so one entry serves both.

codex mcp add chief -- chief mcp

That writes ~/.codex/config.toml:

[mcp_servers.chief]
command = "chief"
args = ["mcp"]

Restart ChatGPT desktop after adding it. ChatGPT on the web cannot reach a local server at all — it takes remote connectors only.

Cursor, Zed, and anything else that reads a JSON MCP config

{
  "mcpServers": {
    "chief": { "command": "chief", "args": ["mcp"] }
  }
}

For Claude Code, check it connected:

claude mcp list
# chief: chief mcp - ✔ Connected

What the agent gets

The initialize response carries the same operating contract distributed with the Chief skill: the two evidence layers, the model-owned acquisition loop, person resolution, structural recall, read-time interpretation, provenance, and write boundaries. An agent that has never heard of Chief should be able to work the surface out from the surface.

Tools

Tool	What it does
`search_artifacts`	Search indexed original artifacts directly — no claim recall, no entity resolution. Start here for source investigation: original excerpts, exact reads, and separate retrieval and coverage receipts. Stored snapshots cannot establish current provider state.
`recall`	Search indexed claims and original source passages, with separate acquisition receipts.
`who`	Resolve a name to an entity record, and return the id to scope `recall` with.
`show`	One claim with its evidence, or an artifact read pinned to recall’s exact version, manifest and chunk coordinates.
`remember`	Record an observation as durable evidence.
`source_search`	Query a source's own API directly — live state, not the index.
`navigate_sources`	Browse indexed source titles, paths and opaque handles without content search, embeddings or provider calls. Entries carry the exact artifact id for `show`; folder entries derive from indexed Obsidian paths, so absence does not prove a note is missing. Continue with `next_cursor` and unchanged filters.
`mail_draft`	Create a Gmail draft on a new thread and return its stable Chief draft id. Never sends.
`mail_edit`	Replace the complete body of an existing Gmail draft in place, using its Chief draft id. Never duplicates or sends.
`mail_reply`	Draft a reply on an existing thread and return its stable Chief draft id. Never sends.
`mail_archive`	Archive a whole conversation. Reversible.
`mail_unarchive`	Return an archived conversation to the Inbox. The inverse of `mail_archive`, and reaches archives from earlier sessions.
`mail_label`	Add and remove labels on one message. The dispositions between archive and leave.
`mail_read`	Mark one message read, so a repeating run stops re-reporting it.
`mail_unsubscribe`	Ask a bulk sender to stop, via its published List-Unsubscribe headers. Leaves the mailbox; cannot be undone.
`mail_send`	Send. Delivers immediately; cannot be undone.
`status`	Reachability, identity, and what the memory covers per source.

These are the CLI's own verbs, and they return the CLI's own output. That is deliberate: the command surface was designed for an agent to read — bounded output, stable ids that are valid arguments to the next call, structured errors, no interactive prompts — so an agent arriving over a protocol reads exactly what one arriving over a shell reads.

Writing to memory

remember records a conclusion. Attribution is the part to get right:

Without from_user, the claim is recorded as the agent's conclusion. This is the safe default.
With from_user, it is recorded as the user's own statement, verbatim, which carries more weight when records disagree.

Never pass from_user for something you inferred. An inference stamped as the user's statement corrupts the record in a way that is hard to undo.

normalized says the user-grounded text is a faithful normalization of what the user said — the same statement, tidied — rather than their words verbatim, so it is never presented later as an exact quote. It must not add a conclusion the user did not state. It requires from_user; a call with normalized and no from_user is refused with [bad_argument].

supersedes marks a claim this observation replaces — for when you watched the correction happen and the meaning lives in the conversation rather than in either claim's text. It requires from_user, because superseding writes a user-authored replacement.

Errors

A tool that fails returns isError: true with the reason as text, not a protocol error. The model is the one that has to decide what to do about it, so it needs to be able to read it. Failures carry a stable code in brackets — [unauthenticated], [bad_argument], [not_found], [rate_limited] — so a harness can branch without parsing prose.

If the machine is not signed in, the server still starts and still lists its tools; calls come back saying to run chief login.

Protocol notes

Transport: newline-delimited JSON-RPC 2.0 on stdin/stdout.
Methods: initialize, tools/list, tools/call, ping.
The server echoes the protocol revision the client asks for. It implements only the stable core, so there is nothing to negotiate away.
Requests are handled one at a time, in order.

Action tools

The write-side verbs are on the tool surface too, returning the CLI's own output. Each names the exact next call in its result.

Tool	What it does
`intelligence`	Whether any machine is understanding your sources: state, machines and their last claim, the harness queue including dead letters, and the remedy named for the machine that needs it — wake wording (`your Mac adil-m3 last ran a turn 3 h ago; on adil-m3: open Chief to resume`) when a turn has ever succeeded, the setup switch only when none has.
`undo`	Reverse a recorded action by the `decision_id` a write tool returned. Proven by the ledger row it appends, written strictly; `[not_reversible]` when no inverse ships; `[reversal_unrecorded]` (not retryable) when the inverse ran but the row could not be written — do not call again, check the target.
`runs_list` / `runs_show`	Local-agent runs on your machines, and one run's approvals, events and receipt.
`runs_approve` / `runs_cancel` / `runs_review`	Let a run start, stop it, record your verdict on its output. Typed refusals: `[invalid_state]` (not in a state that takes it; `runs_show` says which), `[not_found]`, `[core_unavailable]` (retryable, run untouched).
`runs_respond`	Answer an authority request a run raised; `request_key` from `runs_show`, resolved for you when exactly one is pending, `[ambiguous]` naming them when several are. Recorded on the run as answered via the CLI.
`document_create`	A Google Doc, or an Obsidian note applied on the desktop (`pending` when it is offline). Returns the artifact id.
`document_show`	The version an edit must name, editability, and the heading outline.
`document_edit`	Edit against `expected_version`; `[version_conflict]` with the current version and content when the document moved.

The mail write tools now return the ledger decision: behind each effect and undo: chief undo <id> when it can be reversed in one call.