# MCP and coding agents

New to the integration? [Explore Canopod MCP](https://canopod.com/canopod-mcp.html) for a product overview, examples,
and connection steps. This page is the setup and tool reference for version 0.5.

Canopod 0.5 can expose its existing backend to local coding agents through MCP Streamable HTTP. The
agent sees the same repositories, worktrees, services, jobs and configuration as Canopod. It does not
start a second service manager or receive a general shell tool.

MCP is **off by default**. Open **Settings → MCP**, choose the repositories an agent may access, then
enable only the capabilities it needs:

- Discover allowlisted repositories and read cached status, detailed worktree Git/setup state, jobs,
  configured services, bounded redacted logs and public config.
- Create worktrees and run their configured setup scripts.
- Start, stop or restart configured services.
- Update explicitly supported repository and existing-service fields with revision checks.

Dedicated worktree-removal and database-management tools are not exposed in 0.5. They remain disabled
until Canopod has a human approval and audit flow.

## Connect a client

Settings can configure current Claude Code and Codex installations automatically. Manual setup shows
the loopback endpoint and client-specific configuration. Canopod stores the MCP bearer separately from
the application credential and never puts it in a URL. Rotate the token if it may have been exposed,
then reconnect clients.

After connecting, clients can discover the `canopod_worktree_delivery` prompt. It requires an allowed
repository ID and a task, never invents a branch, resolves only the configured or explicit base, polls
durable jobs to completion and distinguishes a running process from verified readiness.

## Tool reference

Canopod 0.5 exposes **15 MCP tools**. Read access is limited to the repositories you allow.
The three write capabilities are separate grants in Settings → MCP.

| Tool | What it does | Permission |
|---|---|---|
| `canopod_repositories` | List allowed repositories | Read |
| `canopod_status` | Read cached worktree and service counts | Read |
| `canopod_worktrees` | List a repository's worktrees | Read |
| `canopod_worktree` | Inspect Git, setup, and service state | Read |
| `canopod_job` | Follow an operation's status | Read |
| `canopod_job_output` | Read bounded job output | Read |
| `canopod_services` | Read configured services and states | Read |
| `canopod_service_logs` | Read recent, bounded, redacted logs | Read |
| `canopod_repository_config` | Read supported public configuration | Read |
| `canopod_create_worktree` | Create a worktree using repository defaults | Worktree creation and setup |
| `canopod_run_setup` | Run configured setup in a linked (non-main) worktree | Worktree creation and setup |
| `canopod_start_service` | Start a configured service | Service control |
| `canopod_stop_service` | Stop a configured service | Service control |
| `canopod_restart_service` | Restart a configured service | Service control |
| `canopod_update_configuration` | Patch supported repository or existing-service fields with revision checks | Configuration |

Configured setup and service commands run on your machine. Configuration permission can change an
existing service command, so grant it deliberately. Patches cannot add or remove services, expose
stored environment values, or automatically restart a running service. There is no general shell tool.

Read tools may use cached state. A running process is not proof that the service is ready; check
readiness separately. Connected AI clients follow their own data handling settings.

## Headless setup

The packaged `canopod-backend` can run without opening the desktop app:

```sh
canopod-backend serve
canopod-backend repo add /path/to/repository
canopod-backend mcp enable --repo REPOSITORY_ID --read-only
canopod-backend mcp smoke --repo REPOSITORY_ID
```

Run `serve` under your own process supervisor. The control commands attach using Canopod's private
application credential; they do not print either credential. `mcp smoke` checks protocol negotiation,
prompt and tool discovery, advertised output schemas, typed cached status, and 25-call p50/p95/p99 latency. It fails when warm p95
exceeds the 50 ms release budget.

> **One owner at a time:**
The desktop app and the headless backend use the same runtime ownership lock and default data. Do not
start both for the same directories. In 0.5 the desktop does not attach as a client to an already
running independent backend.

## Recovery

- **Connection refused:** launch Canopod or start `canopod-backend serve`.
- **Unauthorized after rotation:** reconnect the client so it reloads the private token.
- **Repository denied:** enable that exact registered repository in Settings or with `mcp enable`.
- **Revision conflict:** read repository configuration again, reconcile, then retry once.
- **Interrupted job:** inspect the durable job and output; Canopod never silently replays it.

Browser management and destructive approvals are post-0.5 work. The MCP listener binds to loopback;
remote exposure is unsupported.

---

Canonical page: https://docs.canopod.com/mcp.html
Product version: 0.5.0