Connect an agent
Connect an agent
Agents talk to coachd over MCP at /mcp (spec revisions 2026-07-28 and 2025-11-25).
| Lane | URL | Sign-in |
|---|---|---|
| Public | https://coachd.<domain>/mcp | OAuth: Cloudflare Access, or coachd’s own in built-in mode |
| Private | https://raspberrypi-coachd.<tailnet>.ts.net/mcp | a static token |
Public lane
Settings → Connectors → Add custom connector, with
https://coachd.<domain>/mcp.The app then sends you to sign in:
- Access mode: the Access login; Managed OAuth issues the app’s token. The app’s redirect URI must be allowed on the Access application.
- Built-in mode: coachd’s sign-in, then its consent page. Check the app’s web address (for Claude,
claude.ai), keep or clear the write permission, and approve with your passkey.
Any other client that follows the MCP authorization spec works the same way; one that can’t identify itself with a client metadata document needs dynamic client registration.
Private lane
Over Tailscale, with a token from the host:
docker compose exec coachd /coachd token create --name claude-code --scope read --ttl 90dIt prints the token once. For Claude Code:
claude mcp add --transport http coachd https://raspberrypi-coachd.<tailnet>.ts.net/mcp \
--header "Authorization: Bearer <token>"Other clients take the same URL and header. Manage tokens with token list and token revoke.
Read or write
| Scope | Allows |
|---|---|
| read | every read tool: Garmin data, summaries, goal, notes, workouts |
| write | read, plus coachd’s local writes: request_sync, the goal and notes, propose_workout, cancel_proposal, send_message |
In built-in mode the consent page sets the scope; in Access mode an app gets both. No scope can approve or deliver a workout. See MCP tools.
Next
See an example week of a runner and an agent, and give your agent the starter instructions.
Last updated on