Docs/MCP Guide

MCP Guide

Updated 2026-05-11

MCP Guide

PonderOS speaks Model Context Protocol. Any MCP-capable agent — Claude Code, Cursor, Claude Desktop, OpenClaw, or one you wrote yourself — can read and write your tasks, documents, and projects through a single HTTPS endpoint. You stay in PonderOS. Your agent does the work.

This is a Premium feature.

#Why it matters

You already have an AI that drafts emails, reviews PRs, and writes specs in your editor. Until now, that AI didn't know what was on your to-do list, what was in your vault, or which projects you cared about. With MCP, it does. Ask your agent to "check what's blocked on the Atlas launch" or "file a follow-up task in my Inbox for the meeting we just finished" — it queries and updates PonderOS directly. No copy-paste, no context shuffle.

#Get an API key

  1. Sign in to PonderOS at ponderos.com.
  2. Open Settings → API Keys. (Premium only — Free and Pro tiers see an upgrade prompt.)
  3. Click Create New Key, give it a name like Claude Code or Cursor.
  4. Copy the key the modal shows. You'll only see it once. Treat it like a password — anyone with this key can read and write your data.
  5. The modal also shows a JSON config snippet you can paste straight into your agent's MCP settings.

You can create up to 5 active keys per account and revoke any of them at any time. Revoked keys stop working immediately.

#Key scopes: personal or workspace

When creating a key, the scope dropdown chooses what the key can touch:

  • Personal (default) — the key operates on your personal space only: your own tasks, projects, and vault documents. It cannot see any shared workspace.
  • A workspace — pick one of your workspaces and the key operates on that workspace's shared tasks, projects, and documents instead. Every tool call is scoped to it automatically.

A key has exactly one scope, set at creation and immutable — to work across your personal space and a workspace (or several workspaces), create one key per scope and configure them as separate MCP servers in your agent.

Workspace keys respect membership: your membership is re-checked on every request, so if you leave (or are removed from) a workspace, keys scoped to it stop working immediately — no separate revocation needed.

#Connect your agent

Most MCP clients accept this config shape:

{
  "mcpServers": {
    "ponder": {
      "url": "https://ponderos.com/api/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

Replace pk_live_... with your real key. Save, restart your agent, and it should list 19 PonderOS tools in its tool picker.

#The 19 tools

#Tasks

Tool What it does
task_list List your tasks. Optional filters: status, project, priority.
task_get Fetch one task by id or slug, including its story — the latest 20 comments (author, body, timestamp) so you can read the conversation before acting.
task_create Create a task. Required: title. Optional: description, project, priority, dueDate, assignee, tags.
task_update Update a task's fields by id. Set updates.blockedReason to flag it blocked (mention a ticket like inbox-97 to link the blocker); empty string clears it. task_get/task_list return blockedReason + resolved blockedByTaskIds.
task_delete Delete a task by id.
task_comment Post a comment on a task (id or slug + body), authored as your key's owner. @mentioning a teammate lights their in-app bell and sends the missed-mention email, exactly like the app; @Lumen triggers a Lumen run.

#Documents

Tool What it does
doc_list List all documents in your vault.
doc_read Read a document by id (UUID) or path.
doc_create Create a document. Required: title, content. Optional: folder (defaults to 0-INBOX).
doc_update Update a document by id (UUID) or path. Optional title updates the frontmatter.
doc_delete Delete a document by id (UUID) or path.
doc_move Move and/or rename a document by id or path. Optional: newFolder, newTitle (at least one).
doc_search Full-text search across your vault. Required: query. Optional: limit (default 10).
doc_append Append content to a document by id or path. 1:1 docs get a dated heading. Optional: heading.

#Folders

Tool What it does
folder_create Create a folder at the given path.
folder_move Move and/or rename a folder. Required: path. Optional: newParent, newName (at least one).

#Projects

Tool What it does
project_list List projects. Optional status filter.
project_create Create a project. Required: name. Optional: description.
project_update Update a project's name, description, or status.

#Example flows

These examples show what your agent sends and what PonderOS returns. You won't usually write these by hand — you'll just ask your agent in plain English ("create a task to ship the auth migration") and the agent figures out the call. The shapes below are useful when you're debugging or building your own MCP client.

#1. Create a task from your agent

You say: "Add a task to ship the auth migration this Friday, high priority."

Your agent calls:

{
  "method": "tools/call",
  "params": {
    "name": "task_create",
    "arguments": {
      "title": "Ship the auth migration",
      "priority": "high",
      "dueDate": "2026-05-15"
    }
  }
}

PonderOS returns the new task with a generated id. If you didn't name a project, the task lands in Inbox.

#2. Update task status

You say: "Mark the auth migration task as done."

Your agent looks it up first:

{ "method": "tools/call", "params": { "name": "task_list", "arguments": { "status": "todo" } } }

…finds the matching task, then:

{
  "method": "tools/call",
  "params": {
    "name": "task_update",
    "arguments": {
      "id": "ponder-42",
      "status": "done"
    }
  }
}

The task moves to Done in your kanban instantly.

#3. Create a doc from a conversation

You say: "Save these meeting notes as a doc in my Projects folder."

Your agent calls:

{
  "method": "tools/call",
  "params": {
    "name": "doc_create",
    "arguments": {
      "title": "Auth Migration Kickoff",
      "folder": "1-PROJECTS",
      "content": "# Auth Migration Kickoff\n\n- Decision: cut over Friday\n- Owner: Mo\n- Risks: stale sessions..."
    }
  }
}

PonderOS returns { path, id }. The doc shows up in your vault, browsable in the sidebar.

PonderOS supports linking docs to tasks through the task's linkedDocs array. After creating both, your agent updates the task to reference the doc's id:

{
  "method": "tools/call",
  "params": {
    "name": "task_update",
    "arguments": {
      "id": "ponder-42",
      "linkedDocs": ["7c4f2e9b-..."]
    }
  }
}

Now the task in your kanban shows the linked doc as a chip you can click to open.

#5. Read the story, then comment

You say: "Catch up on the auth-migration task and tell Mo it's ready for review."

Your agent reads the conversation with task_get (the response includes the latest comments under comments), then replies:

{
  "method": "tools/call",
  "params": {
    "name": "task_comment",
    "arguments": {
      "slug": "ponder-42",
      "body": "@mo this is ready for review — migration applied and tests green."
    }
  }
}

The comment is authored as your key's owner. Because it routes through the same path as the app, @mo lights Mo's in-app bell immediately and — if he doesn't see it within ~20 minutes — emails him the missed mention.

#Rate limits and errors

  • 120 requests per minute per key. Auth failures don't count against the budget. If you exceed, you'll get a 429 response with a clear message.
  • 401 — Invalid or expired API key if the key was revoked, expired, or never existed.
  • 403 — upgrade_required if you somehow call /api/keys on a non-Premium account.
  • 404 — Not Found for missing tasks or docs. Tool responses include the original lookup key so you can retry.

#Where to learn more

If you're building a custom MCP client, the MCP spec covers the wire protocol. PonderOS implements the Streamable HTTP transport — single POST /api/mcp endpoint, JSON-RPC payloads, optional SSE streaming.