Connect an AI assistant

Before you start

• PomoDeck 1.5.0 or later, running. The server is part of the app.
• An MCP client. Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and Kiro all work.
• Nothing else. No account, no sign-up, and no internet connection is used by the pairing itself.

Step 1. Get a token

In PomoDeck, open Settings, then Integrations, and pair a client. You will get a token beginning pdk_.

Choose the scopes at this point. Read is enough to look at your tasks and history. Write lets an assistant create and change them. Copy the token now, because it is shown once and only its hash is stored.

Step 2. Add PomoDeck to your client

Paste your token in place of the placeholder.

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

Step 3. Check it works

Restart the client, then ask it what is on your timer. If it answers with your real round type and remaining seconds, you are connected.

Worth approving these automatically, since they change nothing and confirming each one makes the whole thing feel slow:

get_timer_stateget_tasksget_taskget_scheduleget_day_capacityget_focus_patternget_proposal_status

What an assistant can and cannot do

Free on every plan. All read tools. Timer state, tasks, subtasks, schedule, whether a day is realistic, and your focus pattern.

Pro. Write and plan scopes. Creating, editing, scheduling and completing tasks, and proposing a plan you approve.

Never, on any plan. Starting, pausing or skipping the timer. An assistant cannot manufacture a session, so every session in your history is one you actually ran. That is the point of the whole thing, not a limitation we intend to remove.

A record of every tool call, including refusals, is kept locally so you can see what an assistant did.

Using PomoDeck with another tool, such as Todoist

Point the same client at both servers and it can move work between them. Todoist publishes a hosted MCP server, so a common setup is to have your assistant read today's Todoist tasks and add them to PomoDeck.

{
  "mcpServers": {
    "pomodeck": {
      "type": "http",
      "url": "http://127.0.0.1:1314/mcp",
      "headers": { "Authorization": "Bearer pdk_your_token_here" }
    },
    "todoist": {
      "type": "http",
      "url": "https://<todoist-mcp-url>"
    }
  }
}

Get the current Todoist URL from developer.todoist.com. Then ask your assistant to put your Todoist tasks due today into PomoDeck.

One thing to be clear about: this copies when you ask. It is not background sync. The assistant will not notice later changes in Todoist, and completing a task on your timer will not tick it in Todoist.

If something does not work

Full reference

All 18 tools, the three scopes, rate limits and every error code are on the developer docs. Still stuck? Email hello@pomodeck.com and say which client you are using.