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; the daemon does not need to be running. For the HTTP transport or model viewer, start it and check the only public route:

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.

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 and 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; it needs neither the 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.