Skip to Content
GuidesConnecting agents

Connecting agents

pcs connect <client> writes the PCS MCP server into the app’s config. It keeps your other servers, never overwrites a file it cannot parse, and --remove undoes it.

ClientCommandConfig fileAfter connecting
Claude Desktoppcs connect claude-desktop%APPDATA%\Claude\claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Linux: ~/.config/Claude/)Quit Claude Desktop fully and reopen
Cursor (project)pcs connect cursor.cursor/mcp.jsonReload Cursor, Settings, MCP
Cursor (all projects)pcs connect cursor --global~/.cursor/mcp.jsonSame
Claude Codepcs connect claude-code.mcp.jsonRun /mcp and approve the server

Add pcs agents install so the agent is told to call pcs_resume first and pcs_handoff last. Claude Code can also use pcs hooks install. See Hooks and agent instructions.

Options

OptionEffect
--read-onlyNo tool can change anything
--allow-testAlso exposes pcs_test, which is off by default because it runs commands on your machine
--portableWrites plain pcs instead of absolute paths; needs pcs on the app’s PATH

By default the entry is an absolute node path plus script path with --project, because GUI apps have no project working directory and often no PATH.

Agent identity

Models call themselves whatever they like. Writes are attributed to the name the agent passes, else the active session’s agent, else the server’s --agent. pcs_session_start takes an optional name that defaults to --agent, so one tool means one stable identity.

The hook agent name and pcs mcp --agent should match. If they differ, one agent’s work is split over two sessions.

What is tested automatically

CI starts the built CLI exactly as the config file says, from a different working directory (as GUI apps do), over real MCP stdio, and runs resume, notes, session end and handoff.

Manual check in a real app (about 2 minutes)

  1. Run pcs init, then pcs connect <client> in your project, and restart the app.
  2. Ask the agent: “Call pcs_resume, add a next note saying ‘check the connect docs’, end the session, then show the handoff.”
  3. Run pcs handoff in a terminal. The note must appear, marked reported.
  4. Run pcs verify. It must say the log is intact.

If the tools do not show up

Run pcs doctor, check the config path in the table above, and confirm the app was fully restarted.

Last updated on