MCP Integration

Point Claude Code, Cursor, Claude Desktop, or any MCP-compatible client at your CoachKeeper workspace.

What this is

CoachKeeper exposes its full agent toolset over the Model Context Protocol (MCP) — the open standard that AI clients use to talk to external tools. Any MCP-compatible client can read, search, create, update, and schedule against your workspace as if it were the built-in coach.

Same rules apply on both sides:

Same authentication boundary — OAuth sign-in with your CoachKeeper account, never a pasted secret
Same action log — every create / update / delete lands in the shared action log the in-app coach uses
Same undo — ask the in-app chat assistant to undo any action taken over MCP
Same availability windows respected when scheduling

Why you’d use it

You already live in Cursor or Claude Code. Let the editor turn a TODO comment into a real todo in your backlog without leaving the IDE.
You use Claude Desktop every day. Ask it to schedule your week using your CoachKeeper backlog and availability — without copy-pasting.
You’re building your own agent. Treat CoachKeeper as a managed PKM service it can call.

Connect a client

There is nothing to mint, copy, or paste. CoachKeeper implements the MCP authorization spec (OAuth 2.1): you give your client the server URL, and the first time it connects your browser opens a CoachKeeper consent screen. Sign in (if you aren’t already), click Authorize, and you’re done — the client refreshes its own access from then on. This is the same flow GitHub, Linear, Notion, and Sentry use for their MCP servers.

Claude Code (CLI)

claude mcp add --transport http coachkeeper https://api.coachkeeper.com/api/v1/mcp

Confirm with claude mcp list. On first use it will open your browser to authorize.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "coachkeeper": {
      "type": "http",
      "url": "https://api.coachkeeper.com/api/v1/mcp"
    }
  }
}

Restart Claude Desktop. Look for the 🔌 icon in the input bar — it should list coachkeeper and prompt you to authenticate.

Cursor

Settings → MCP → Add new MCP server, paste the same JSON snippet.

Anything else that speaks MCP

Same JSON shape. Two things matter: type: "http" and the URL. No headers — the client discovers the OAuth endpoints automatically and walks you through consent. The client does need to support MCP OAuth: harnesses whose MCP client only takes static headers (DeepSeek Harness at time of writing, for example) can’t sign in yet.

Teach your agent

Connecting gives your agent the tools; teaching it the house style makes it good with them. Settings → AI Tools (MCP) includes a short copyable briefing — the entities and how they relate, how to search cheaply before listing everything, how notes and todos are formatted, and what to confirm with you before changing things.

Claude Code: download it as SKILL.md and save it under ~/.claude/skills/coachkeeper/ — it loads automatically whenever you work with CoachKeeper.
Claude Desktop / ChatGPT / Cursor and others: paste it into the agent’s custom or project instructions.

The server already sends a compact version of this briefing to every client when it connects, and it also serves the full briefing over MCP itself — as the skill prompt (a slash command in Claude Desktop) and as the resource coachkeeper://skill. A client that shows prompts can load it in one click, no pasting; installing the SKILL.md file is still worth it if you pair one agent with CoachKeeper regularly, so it is there before the first tool call.

Connection status at a glance

Once a client is connected, a small plug/agent icon in the app’s top bar turns into a status badge — amber when idle, briefly green whenever the agent makes a change. Click it anytime to jump straight to Settings → AI Tools (MCP). Before you’ve connected anything, the chat panel also shows a one-time “bring your own agent” card pointing at the same setup flow.

Managing access

Settings → AI Tools (MCP) lists every client currently connected to your account, with when it connected and when it was last used. Revoke cuts a client off immediately — it would have to go through browser consent again to reconnect.

Under the hood, each authorization issues a short-lived access token plus a rotating refresh token. A connection that goes unused for more than 7 days expires on its own; active clients renew silently and stay connected indefinitely.

What the AI client can do

The server exposes the same tools the in-app coach uses, minus four that are app-specific: undo_last_action, request_include_context, request_approval (your own agent runs its own approval flow), and web_search. At time of writing:

Domain	Tools
Notes	`list_notes`, `get_note`, `create_note`, `update_note`, `delete_note`, `summarize_note`, `rewrite_note`
Notebooks	`list_notebooks`, `get_notebook` (table of contents, or the whole book as markdown), `create_notebook`, `update_notebook`, `delete_notebook`
Todos	`list_todos`, `get_todo`, `create_todo`, `update_todo`, `delete_todo`, `complete_recurring_todo`
Agent runs	`list_agent_tasks`, `claim_todo`, `report_run`, `accept_run`, `revise_run`, `discard_run`, `evidence_upload`, `settle_git`
Events	`list_events`, `get_event`, `create_event`, `update_event`, `delete_event`
Sources	`list_sources`, `get_source_content`, `search_sources` (RAG)
Search	`search_items` (cross-entity by title or content), `semantic_search` (meaning-based, not just keyword matches)
Tags	`list_tags` (every tag with live item counts), `get_tag_dossier` (a tag’s map: a mermaid concept sketch of what’s filed under it plus short state notes, each pointing at real item ids — the same map the Library page shows, including any arrangement you made by hand, which a client is told not to redraw), `update_tag` (rename, recolor or describe a tag — a rename reaches every item under it), `merge_tags` (fold one tag into another), `delete_tag` (items are kept and lose the tag; a tag that still has items is refused until the client confirms with `untag_items`)
Orientation	`get_workspace_overview` (a snapshot of your workspace — counts, recent activity — for a client to get its bearings before diving in)
Scheduling	`get_availability`

Notes, todos, and sources read back as properly formatted markdown, not raw JSON blobs. Their list tools (list_notes, list_todos, list_sources) are paginated and filterable — by status, tag, notebook, due window, or title — instead of a flat cap on how many rows come back, so a client can page through a large workspace without missing items. Notes can be tagged the same way todos and events already could.

A todo carries two independent dates, and the tools keep them apart: due_date is the deadline, scheduled_start / scheduled_end is the time blocked out to do the work — which is what your calendar shows. Blocking time means scheduling the todo itself; an agent should never create an event to stand in for a task. list_todos filters on either (due_before / due_after, scheduled_from / scheduled_to) and takes unscheduled: true to find work that still needs a slot.

Two writing conventions worth teaching your agent: a fenced ```mermaid code block in any note renders as a live diagram in the app, and rich material for a todo — briefs, research, diagrams — belongs in a note linked via context_note_ids, which is what the todo page displays.

Each tool returns the same shape as a normal API call and produces the same action log entry. To see the live, authoritative list, call MCP’s standard tools/list from your client.

Work your agent tasks

Tasks you hand over on the board (the Agent column — see Hand a task to your agent) are worked from your own agent, when you say so. The server ships three prompts for it — slash commands in Claude Code (/mcp__coachkeeper__<name>) and prompts in Claude Desktop:

agent_tasks — My agent tasks: lists what needs you, what’s queued, what’s running and what’s waiting for your review, and lets you choose: work one, work up to three, answer a question, accept, revise or discard. With the CoachKeeper skill installed in Claude Code, /coachkeeper does the same.
work_task — work one task, by id or title.
work_queue — work through the queue, oldest first, up to three.

Each task is worked as a run: the agent claims it (claim_todo — so two agents never take the same task), works, and reports (report_run — done with a summary, or needs input with its questions). Everything it writes in CoachKeeper in between belongs to that run, so the card can show exactly what changed and Discard can undo it as one. accept_run, revise_run and discard_run are your decisions, which the agent relays when you say so — it is told to list what a discard will undo and wait for your yes. There is no chat thread to keep alive — the task is the thread — so a question you answer on Tuesday can be picked up by a different agent session on Thursday.

If a tag has an agent folder (relative, e.g. coachkeeper — never a full path), its tasks carry it, and an agent with file access works only inside it: in git it works in a throwaway copy (.ck/worktrees/, removed before it reports) and leaves one branch per task, ck/todo-<id>-…, holding one squashed commit, never pushed. It reports the files, the branch, the computer and the tests. A folder missing on the current computer is skipped, so the task waits for the machine that has it. The folder can also hold several repos — a project made of an api and a web repo, say: the agent works in whichever repos the task concerns (asking if it can’t tell), one branch each, and the card shows each repo’s state.

Branches follow the card. Accept means merge, Discard means remove: the next time your agent runs on that computer, list_agent_tasks hands it the branches you’ve decided on (git_to_settle) and it fast-forwards your branch or deletes theirs, then records it with settle_git — one line, no questions. If git refuses the merge (you changed the same lines since), the task comes back to your review saying why. In Claude Code, the permissions snippet in Settings → MCP lets these git steps run without a prompt each time; pushing is never included.

Evidence. Every report shows before → after — up to three proofs, the strongest first: tests before and after, the key line that changed, or screenshots. Screenshots go from the agent’s shell straight to a short-lived upload link (evidence_upload), never through its context. A run that can’t show proof says why.

Run the queue on a schedule

CoachKeeper never starts an agent by itself; queued tasks wait for a client to come by. If you want that to happen without you, schedule the client. Settings → AI Tools (MCP) → Put the queue on a schedule has the instructions to give it — the server serves the same text as the queue_routine prompt and the resource coachkeeper://queue-routine. They are work_queue made safe for a run nobody is watching:

It stops at once when the queue is empty, without changing anything — so a frequent schedule costs next to nothing.
A few tasks per run, oldest first, one at a time. A task an earlier run abandoned mid-way is picked back up after an hour.
It never asks a question into the void. Anything it can’t decide becomes Agent needs input on the card, with the question written on the task. Answer it on the task or from Today, and the next run resumes where it stopped.
Every result is a one-pager: a new note linked to the task and filed under its tag — the answer first, then what it found or did, one diagram or table only when the content calls for one, next steps, and sources. The task moves to your Pending column for review.

Where to schedule it:

Claude Desktop, on your own computer — Code tab → Routines → New routine → Local. Paste the instructions, choose the folder that holds your projects as the working folder, and pick a schedule. Press Run now once and choose Always allow for each CoachKeeper tool it asks about; later runs then go through without stopping. A local routine only fires while the app is open and the computer is awake — after sleep it catches up with a single run.
Claude Code — with the server added (claude mcp add … above), one cron or launchd line run from your projects folder: claude -p "Run the queue_routine prompt from the coachkeeper server".
Claude in the cloud — a cloud routine at claude.ai/code/routines with the CoachKeeper connector runs with your laptop closed, hourly at most. It can research and write; it cannot reach files on your computer.
ChatGPT — a scheduled task with the CoachKeeper connector and the same instructions. Research and writing only.
Any other headless agent with an OAuth-capable MCP client works the same way: point it at the server, have it load the queue_routine prompt, run it on whatever timer you like.

Guardrails still apply: the agent can only do what a person with your account could. What it did while you were away is listed on Today, where each line can be compared or undone.

Things to know

Streamable HTTP, stateless. No persistent connection — every request carries a short-lived bearer token the client manages for you.
No per-request rate limiting today. MCP tool calls are exempt from the web rate limiter. Be a good citizen — reasonable limits may be introduced later.
Legacy static tokens (from before OAuth) keep working until they expire, but you can’t mint new ones. Reconnect via OAuth — it’s less work and it never dies silently.
Self-hosted CoachKeeper? Same protocol, just point at your own https://your-host/api/v1/mcp.

Troubleshooting

Symptom	Likely cause
Client reports the server is unreachable	Wrong URL — must end in `/api/v1/mcp` (not `/mcp`)
Browser consent never opens	Your client predates MCP OAuth support — update it
`401 Unauthorized` on every call	Connection was revoked or expired from inactivity — reconnect (the client will re-open the consent screen)
Tool calls succeed but nothing appears in the app	You authorized while signed in to a different CoachKeeper account — revoke in Settings and reconnect with the right one
Client lists no tools	Server reachable but not yet authorized — trigger the auth flow (e.g. `/mcp` in Claude Code)

Where the actions show up

Changes made over MCP push to your open CoachKeeper views in real time — a todo created from Cursor appears on your Kanban board instantly, no reload. Each action is also recorded in the same action log the built-in coach uses, so if an external client did something you didn’t want, open the in-app chat and say “undo that” — the assistant rolls it back.