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.

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, save_memory, request_include_context, 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`
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)
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`
UX	`request_approval` (used by the agent before bulk operations)

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.

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.

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.