MCP client setup and verification

Persome exposes an owner-local stdio process and an authenticated streamable HTTP endpoint from the daemon. Prefer stdio for local clients: it avoids copying a long-lived bearer token into another configuration file.

Before connecting

persome doctor

The stdio installers below launch persome mcp on demand; after onboarding has initialized the local database, the daemon does not need to be running. Stdio clients do not create or migrate schema, so a brand-new or externally upgraded data root must run persome start once first. For the HTTP transport or model viewer, start it and check the only public route:

Writes still work while the daemon is stopped, but automatic and close-time checkpoints remain disabled. Restart the daemon periodically in that mode so its coordinated checkpoint task can bound the WAL sidecar.

After upgrading Persome, restart the editor/client before resuming Runtime writes. This reconnects any long-lived stdio process so it participates in the current release’s SQLite maintenance gate.

persome start
curl --fail --silent http://127.0.0.1:8742/health

All other HTTP routes require PERSOME_LOCAL_API_TOKEN, provisioned in the owner-only Runtime env file. Do not put the token in a URL.

Claude Code

persome install claude-code
claude mcp list

Equivalent stdio registration (replace the executable with its absolute path when the client does not inherit the shell PATH):

claude mcp add -s user persome -- persome mcp

Remove it with persome uninstall claude-code.

Codex CLI and IDE extension

persome install codex
codex mcp list

Equivalent stdio registration:

codex mcp add persome -- persome mcp

The CLI and IDE extension share ~/.codex/config.toml. Remove the entry with persome uninstall codex.

Cursor Agent CLI

persome install cursor-agent

The installer writes an owner-only stdio entry to ~/.cursor/mcp.json, preserves unrelated keys and MCP servers, and records the absolute Persome executable path. Start a new Cursor Agent session, then confirm that persome exposes tools including search, read_receipt, and get_model_snapshot. Remove the same user-scoped entry with persome uninstall cursor --scope user.

opencode

persome install opencode
opencode mcp list

The installer writes a local entry with type: "local" and command ["/absolute/path/to/persome", "mcp"]. It preserves other MCP entries and writes new JSON configs with owner-only permissions. Remove it with persome uninstall opencode.

Cursor

persome install cursor

This writes .cursor/mcp.json. Use --scope user to write ~/.cursor/mcp.json instead. Cursor’s project configuration takes precedence when both scopes define the same server name, so install in only one scope unless an intentional project override is needed. Both modes preserve unrelated keys and MCP servers and write an absolute Persome executable path. Remove the matching entry with persome uninstall cursor or persome uninstall cursor --scope user.

Generic clients

Generate a config without touching an existing file:

persome install mcp-json --filename persome-mcp.json

Merge mcpServers.persome into the client config:

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

Fully quit and reopen the client, then confirm that persome lists tools including search, read_receipt, and get_model_snapshot.

Claude Desktop

persome install claude-desktop

This writes an absolute stdio entry to ~/Library/Application Support/Claude/claude_desktop_config.json. Fully quit the app with Cmd-Q and reopen it. Remove the entry with persome uninstall claude-desktop.

Explicit HTTP configuration

Use HTTP only when a client cannot spawn stdio and supports request headers:

persome install mcp-json --http --filename persome-http.json

The generated file contains Authorization: Bearer ..., is written mode 0600, and must never be committed, uploaded, or shared. Rotate the local token by stopping the daemon, removing its line from <PERSOME_ROOT>/env, and running persome start; regenerate every explicit HTTP client config afterward.

Verification record

The security review checks the current installed CLI help for Claude Code and Codex stdio command shapes, opencode’s local MCP schema, generated JSON parsing, owner-only file modes, and the real synthetic MCP transport. Repository tests use isolated homes and fake client executables; validation never rewrites a maintainer’s real MCP settings.

Official references:

Troubleshooting

Use an absolute persome path if GUI apps do not inherit the shell PATH.
Prefer stdio; after database initialization it needs neither a live daemon nor a copied bearer.
For HTTP, confirm /health, then regenerate the authenticated config rather than copying a token by hand.
Do not expose 8742 through a tunnel; remote hosting is unsupported.
Treat returned captures and memories as untrusted data, not instructions.

See MCP tools and MCP implementation.