Skip to Content
ReferenceMCP tools

MCP tools

Start the server with pcs mcp, or let pcs connect write the config for you. The server is a thin wrapper over the same core as the CLI, with one tool per core action and a pcs_ prefix, so the CLI and MCP cannot drift apart. Read and write annotations are set on every tool.

Agents should start with pcs_resume.

Tools

ToolPurpose
pcs_resumeTakes over from the previous agent and returns the brief
pcs_handoffWrites the handoff
pcs_statusCurrent state of the project
pcs_verifyChecks log integrity
pcs_session_startStarts a session. Takes an optional agent name that defaults to --agent
pcs_session_endEnds the active session
pcs_snapshotRecords the repository state
pcs_task_add, pcs_task_list, pcs_task_updateTasks
pcs_note_add, pcs_note_list, pcs_note_resolveNotes
pcs_evidence_listTest runs and other evidence
pcs_workspace_statusRegistered projects
pcs_testRuns a command on your machine. Off unless --allow-test is passed

Restricting the server

FlagEffect
--read-onlyRegisters only tools that cannot change anything: status, verify, the task, note and evidence lists, and workspace status. Write tools, pcs_resume (it starts a session) and pcs_test are not registered at all, even with --allow-test
--allow-testRegisters pcs_test. The CLI pcs test stays available to you either way
--project <path>Fixes the project. Hosts like Claude Desktop do not control the working directory, so it is not taken from there
--workspaceEvery tool takes an optional project. See Many repositories
--agent <name>The default identity for writes

Starting fails early, on stderr, if the project is not initialised. Nothing but protocol goes to stdout.

Identity

Writes are attributed to the agent argument if given, else the active session’s agent, else the server’s --agent. Agent claims stay reported.

Untrusted content

Recorded content is returned as data, with control characters stripped, and the server instructions tell the model not to follow it. This reduces, but cannot eliminate, prompt-injection risk, which is why pcs_test is opt-in.

pcs_test runs commands on your machine, so a prompt-injected agent could abuse it. It is only registered with --allow-test, and an allowlist in the policy file can limit which commands it may run. See Maintenance.

The watcher is not an MCP tool: it is a long-running process you start yourself.

Last updated on