Expose the local backup state to agents without building a second control plane.

How to start it

./notesctl mcp

v1 uses stdio transport only. It is designed for local MCP hosts and local tooling, not for exposing the workflow over a remote HTTP control plane.

Minimal host launch shape

If your local MCP-aware host can spawn stdio servers, the truthful launch contract is just the repo entrypoint plus the mcp command.

{
  "command": "/absolute/path/to/notesctl",
  "args": ["mcp"]
}

Hosts differ in where they store this configuration, so this page documents the runtime shape instead of pretending one config file works everywhere.

Exact repo-owned help and quick verification

• ./notesctl help mcp is the narrow contract summary for the MCP surface
• After attach, verify that the host can see get_status, run_doctor, verify_freshness, get_log_health, list_recent_runs, and get_access_policy
• Read notes-snapshot://recent-runs or call get_status before you assume the local snapshot loop has already been initialized

Need host-by-host status and copyable examples? Open the Builder Integration Pack.

Need the repo-owned attach checklist? Use post-attach-checklist.md so you can separate repo-side proof from host-side proof in one pass.

Official host docs to pair with this page

• OpenAI Docs MCP reference for current Codex-side MCP setup patterns
• Claude Code MCP guide for current local stdio and remote MCP registration flows
• Model Context Protocol introduction for the shared protocol vocabulary

This page documents the Apple Notes Snapshot side of the contract. Use the official host docs above when you need the current host-specific registration details.

Where it fits in the AI and agent stack

• Best fit: MCP-aware coding agents and local automation hosts that want the same backup facts as a human operator
• Natural neighbors: Codex- and Claude Code-style local workflows when the host can launch stdio MCP servers
• Not claimed here: a hosted agent platform, an OpenHands replacement, or a generic AI assistant runtime

Current v1 tools

• get_status
• run_doctor
• verify_freshness
• get_log_health
• list_recent_runs
• get_access_policy

How each tool maps to the deterministic substrate

• get_status -> ./notesctl status --json
• run_doctor -> ./notesctl doctor --json
• verify_freshness -> ./notesctl verify
• get_log_health -> ./notesctl log-health --json
• list_recent_runs -> ./notesctl aggregate --tail N
• get_access_policy -> ./notesctl audit --json

This is why the MCP surface stays truthful: it is a thin agent-facing layer over the same repo-owned control-room facts, not a second business system.

Current v1 resources

• notes-snapshot://state.json
• notes-snapshot://summary.txt
• notes-snapshot://recent-runs
• notes-snapshot://config-safe-summary

Why the first batch is read-only

• The workflow stays anchored to the existing notesctl contract.
• It avoids turning the MCP surface into a second business system.
• It keeps high-side-effect actions out of scope until the agent-facing contract proves useful.

Current substrate, and what is still missing

• Current substrate: notesctl, state.json, aggregate summaries, and the read-only MCP tool/resource surface
• Still missing on purpose: public OpenAPI, generated clients, shared SDK packages, and write-capable MCP tools
• Truthful builder entry today: start from the CLI contract or the stdio MCP contract, not from a pretend hosted API

What it does not do in v1

• No remote HTTP MCP exposure
• No vendor updates
• No destructive cleanup tools
• No note-content reads

How MCP differs from the local Web API

• MCP: stdio-first, host-to-tooling contract for MCP-aware agents
• Local Web API: token-gated browser and same-machine HTTP surface behind ./notesctl web
• Shared truth: both sit on top of the same repo-owned status, doctor, log-health, aggregate, and access-policy surfaces
• Still not claimed: neither surface becomes a public OpenAPI or hosted control plane

If your workflow already runs through the local Web console or same-machine HTTP clients, open the Local Web API guide next.