MCP Connector LIVE · Pro & Team

The TwigDo MCP connector lets your AI agents read and update your task trees directly. Point Claude Code, Kimi, Hermes Agent, or another MCP-compatible client at your account and it can list projects, inspect branches, add tasks, check things off and keep your tree moving — while you see every change live in the app.

Two ways in

Pick by what your client can do. Apps that let you set a header take a token you paste; apps that only offer a “connector” or “custom integration” box use the sign-in flow. Both reach the same server with the same powers.

A · Sign in (claude.ai, Claude Desktop, mobile)

B · Paste a token (Claude Code, Kimi, Hermes, your own scripts)

Client configuration

Claude Code:

claude mcp add --transport http twigdo https://mcp.twigdo.com/mcp \
  --header "Authorization: Bearer twig_your_token_here"

Kimi, Hermes, or another MCP client (JSON config):

{
  "mcpServers": {
    "twigdo": {
      "type": "http",
      "url": "https://mcp.twigdo.com/mcp",
      "headers": {
        "Authorization": "Bearer twig_your_token_here"
      }
    }
  }
}

The protocol

An agent that can edit a board is useful. An agent that has to lay the work out before it starts, and account for it when it finishes, is the reason TwigDo exists. So the connector does not just offer tools — it expects a sequence, and checks it.

1. Claim. twigdo_start_task takes the branch and hands back the project brief, the task's place in the tree, the whole branch with its ids, the active sprint and the decisions already taken. There is no separate "remember to read the context" step, because claiming is reading it.
2. Plan. twigdo_plan_task breaks the work into sub-tasks before any code is written, so the plan appears on your board while you can still change it rather than after the fact.
3. Work. While an agent holds a claim, that task and everything under it are its to change. Nothing else is. One claim at a time.
4. Report. twigdo_complete_task takes a sentence on what was actually built, saved onto the task itself — and twigdo_release_task hands a branch back with the reason when an agent is stuck, instead of leaving you to work out why it went quiet.

Completing work without rewriting agent.md builds a visible debt, which is what makes the brief actually get written rather than merely asked for.

How hard this is imposed is yours to set, per project, from the Agent menu → Agent protocol, or in the Project Context dialog:

Level	What happens
Off	Nothing is checked. Agents change what they like, in any order.
Guided (default)	Nothing is refused, but a call made out of sequence comes back with the correction attached. Most agents read that and fall into line.
Strict	A write outside the claimed branch is refused outright, and an agent that owes the brief a rewrite cannot claim anything new until it writes one.

Agents can read the setting. No tool changes it — a guardrail an agent can lower is decoration.

While an agent holds a task, the board says so: a live pill on the task, the agent's own sentence about what it is doing, and a blocked marker with the reason on anything it gave up on. That is the point of the whole thing — you stop scrolling back through a terminal to find out what was decided and what is left.

Available tools

Tool	What it does
twigdo_start_task	Claim a branch and get the brief, the tree and the decisions
twigdo_plan_task	Break the claimed task into sub-tasks, in one call
twigdo_complete_task	Finish a task with a note on what was built
twigdo_release_task	Hand a task back, blocked, with the reason
twigdo_record_decision	Record a choice and its reasoning, replayed to every later agent
twigdo_create_project	Start a new project from scratch
twigdo_list_projects	List your projects (name, progress, linked parents)
twigdo_get_tree	Read a project's full task tree
twigdo_add_task	Add a task or sub-task under any node
twigdo_toggle_task	Mark a task complete / reopen it
twigdo_rename_task	Rename any task
twigdo_remove_task	Remove a task (and its branch)
twigdo_set_due_date	Set or clear due dates and reminders
twigdo_list_sprints	See the project's sprints and which one is active
twigdo_create_sprint	Create a timebox with a name, dates and a goal
twigdo_start_sprint	Make a sprint the active one, closing the last
twigdo_set_task_sprint	Pull a task into a sprint, or take it out
twigdo_guide	How TwigDo works and the protocol expected of agents
twigdo_read_context	Read the project's agent.md brief
twigdo_write_context	Rewrite that brief for the next agent

Sprints

A sprint is a named stretch of time with a goal, and a set of tasks pulled into it from anywhere in the tree. Tasks do not move — a sprint says when you are doing something, not where it belongs — so a fortnight's work can cut across branches without flattening the structure that makes the tree useful.

Agents are asked to check twigdo_list_sprints before picking up work, so they pull from the current commitment rather than the open backlog, and to put anything they add for that timebox into the sprint with twigdo_set_task_sprint. Creating and starting sprints is left to the owner: the cadence is a human decision, and an agent inventing one is a surprise nobody asked for.

The agent brief

Every project carries an agent.md: a short markdown file holding what an agent needs told before it starts — the stack, the constraints, the decisions already taken. Agents read it with twigdo_read_context before planning and rewrite it with twigdo_write_context when they finish, so the next one picks up where the last left off instead of starting cold. Humans edit the same file from Agent → Project Context in the app. It is stored with the project, not on any one machine, so every agent sees the same brief; the download is an export for anyone who wants a copy in their own repo alongside the code it describes.

It is a briefing, not a log — agents are asked to compact it rather than append, because the whole file is re-sent on every request. The Activity feed is the log.

Beside it sits the decision log. twigdo_record_decision takes a choice and the reasoning that settled it — the library picked, the schema fixed, the approach tried and rejected — and every agent that claims a task afterwards is shown it before it plans anything. Three kinds of memory that do not overlap: the brief is what you would tell someone over coffee, the decisions are why things are the way they are, and the feed is what happened. It is the reason a project's memory can live with the project instead of in a second tool you have to remember to update.

Scope & safety

• Tokens are scoped per account and can be revoked anytime from the same menu — revoking takes effect on the very next request.
• Only a SHA-256 hash of each token is stored, so a database leak cannot reveal a working token. The same is true of everything the sign-in flow issues — authorization codes, access tokens, refresh tokens.
• An app you sign in to holds an hour-long access token that renews itself, not a permanent key. Approving the same app again replaces its access rather than granting a second lot, and disconnecting it kills both halves at once.
• Tokens stop working the moment an account drops off an eligible plan.
• Agents only reach projects your account owns. A project someone else shared with you is outside what your tokens can read or change — narrower than your own access, deliberately.
• Every agent change syncs like a normal edit and is recorded in the project's Activity feed, stamped with the token that made it. Undo is a local history of your own edits, so an agent's change is not something you can Ctrl-Z — reopen or delete the task instead.

Limits

Agent tokens are for your agents, not a way to give another person access without a seat. Three things keep that honest:

• A cap per plan. Solo Pro and Founder Lifetime issue up to 3 tokens; Team Block gets two per seat (minimum 5). Revoke one to issue another. Apps you connect by signing in do not count against it — connecting Claude on the web, the desktop and your phone should not cost you the tokens you keep for your own agents.
• A rate limit per token. Each token gets 120 calls a minute. That is generous for one agent and uncomfortable for several people sharing one, so give each agent its own token.
• One agent at a time. Solo Pro and Founder Lifetime run one live agent; Team Block runs one per seat. A connection lasts until another agent takes it — nothing expires on a timer, so an agent that pauses to think keeps its slot. Sending initialize claims the connection: the agent that was holding it is superseded and gets a 409 on its next call, naming whoever took over and telling it that reconnecting takes the slot back. An agent that is finished should send an HTTP DELETE to release it straight away, and you can release a stuck one from Agent tokens in the app.
• An identity on every change. Anything an agent creates or edits is stamped with the token that did it, and the app shows a robot badge with that token's label next to the task. Every change also lands in the project's Activity feed, so you get the whole history rather than just the last writer.

Collaborating with other people works through seats instead: invite them from File → People & Access. Each collaborator needs their own TwigDo account and takes one of your plan's seats.

The connector is included with Solo Pro, Founder Lifetime and Team Block. See pricing →