PomoDeck developer docs

Quickstart

1. 1. Install PomoDeck from the Microsoft Store and launch it. The server is off until you pair a client.
2. 2. Open Settings, Integrations. Name the client, choose its scopes, and pair. The token is shown once.
3. 3. Paste the config below into your client and restart it.
4. 4. Ask the assistant what is on your schedule. If it can answer, the read scope is working.

Check it without a client

curl -X POST http://127.0.0.1:1314/mcp \
  -H "Authorization: Bearer pdk_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Endpoints

Auth and scopes

18 tools

Call tools/list for the authoritative schemas. The app is the source of truth; this list is here so you know what exists before you install anything.

read · 7 tools · free on every plan

• get_timer_stateRound type, running or paused, elapsed and total seconds.
• get_tasksOpen tasks due today or earlier, plus unscheduled ones.
• get_taskOne task in full, including description and subtasks.
• get_scheduleTasks by date, with per-day counts. Defaults to four weeks.
• get_day_capacityWhether a day's plan fits what the user finishes on that weekday.
• get_focus_patternPer-weekday completions, per-hour flow, peak hours, estimate accuracy.
• get_proposal_statusWhether a proposed plan is pending, approved, rejected or expired.

write · 10 tools · Pro

• create_taskAdd a task with an estimate, quadrant, date, time and subtasks.
• handoff_to_humanHand back work an agent cannot finish, with the reason and ordered steps.
• update_taskChange title, description, estimate or quadrant.
• schedule_taskAssign a task to a date, optionally a time. Omit the date to clear it.
• complete_taskMark a task done.
• delete_taskRemove a task. Soft delete, the record survives.
• add_subtasksAppend ordered, tickable steps. Appends, never replaces.
• set_subtask_doneTick or untick one step.
• update_subtaskRewrite one step's text.
• delete_subtaskRemove one step.

plan · 1 tool · Pro

• propose_planSubmit a batch of changes for approval. Writes nothing, returns a diff and a capacity check per date.

There is no start_timer.An assistant cannot start, pause or skip the timer, by design. It means no session in the history can be fabricated, so the statistics are evidence of real work. If you need an agent that logs focus time on a user's behalf, PomoDeck is the wrong tool.

Client config

Claude Desktop, Claude Code, Cursor, Windsurf, Kiro, ChatGPT and anything else that speaks MCP over HTTP:

{
  "mcpServers": {
    "pomodeck": {
      "type": "http",
      "url": "http://127.0.0.1:1314/mcp",
      "headers": { "Authorization": "Bearer pdk_..." }
    }
  }
}

VS Code, which uses servers rather than mcpServers:

{
  "servers": {
    "pomodeck": {
      "type": "http",
      "url": "http://127.0.0.1:1314/mcp",
      "headers": { "Authorization": "Bearer pdk_..." }
    }
  }
}

Two things that silently break setup

• VS Code uses servers. Every other client uses mcpServers. The wrong key fails with no useful message.
• "type": "http" is required. Without it several clients try stdio, then report an error that does not name the cause.

Recommended autoApprove

The read tools mutate nothing, and a confirmation prompt on each one makes the integration feel slow. Auto-approve get_timer_state, get_tasks, get_task, get_schedule, get_day_capacity, get_focus_pattern and get_proposal_status. Leave the write and plan tools prompting.

Errors

Transport failures come back as JSON-RPC errors: -32700 parse error, -32601 unknown method, -32603 internal, -32001 auth, which is the only one that also sets a non-200 status.

Tool failures come back inside a successful tools/call result with isError: true, so the model sees them instead of the transport swallowing them. The text starts with one of these codes:

• forbiddenThe token does not hold the scope this tool needs.
• rate_limitedMore than 60 writes in a minute on one token.
• bad_requestA required argument is missing, or a date or time did not parse.
• not_foundNo task, subtask or proposal with that id.
• invalid_planpropose_plan could not read the change set.
• unknown_toolNo tool with that name.
• internalDatabase or timer unavailable.

OpenAPI spec

Something not working

Connection problems are covered on the support page. For anything else, open an issue on GitHub or email hello@pomodeck.com.