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

Sign in to PonderOS at ponderos.com.
Open Settings → API Keys. (Premium only — Free and Pro tiers see an upgrade prompt.)
Click Create New Key, give it a name like Claude Code or Cursor.
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.
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.

#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 13 PonderOS tools in its tool picker.

#The 13 tools

#Tasks

Tool	What it does
`task_list`	List your tasks. Optional filters: `status`, `project`, `priority`.
`task_get`	Fetch one task by id.
`task_create`	Create a task. Required: `title`. Optional: `description`, `project`, `priority`, `dueDate`, `assignee`, `tags`.
`task_update`	Update a task's fields by id.
`task_delete`	Delete a task by id.

#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`.

#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.

#4. Link a doc to a task

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.

#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

Getting Started — sign-in, first note, meet Lumen.
User Guide — the full tour: vault, tasks, projects, sharing.
Troubleshooting — common issues.

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.