MCP and coding agents
New to the integration? Explore Canopod MCP 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:
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_IDRun 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.
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.