Every AI tool you use, one to-do list.

Connect in one step

Paste this into your agent, whichever one you use:

Connect to Koma, my task app, as an MCP server at https://koma.ac/api-preview/mcp (Streamable HTTP, OAuth 2.1 with PKCE and dynamic client registration; the first call answers 401 with the discovery address). If you have a built-in way to add an MCP server with OAuth (a connector, a settings screen, an "mcp add" command), use it. If you have none, connect over OAuth as plain web requests, nothing installed: 1) the first POST to that address answers 401 and names the discovery address; register yourself there (dynamic client registration) with a loopback redirect such as http://127.0.0.1:8585/callback; 2) generate the authorization link with PKCE and send it to me; 3) I open it, sign in and approve, and paste you the 127.0.0.1 link the browser lands on, within ten minutes; 4) exchange the code in it for a token, keep the token, and call the tools at that address with it (JSON-RPC over HTTP: tools/list, then tools/call). Before you open the sign-in link, tell me what will happen: I sign in and approve in my browser, and if the page after that does not load, I copy that page's link and paste it back to you; and if the sign-in window does not open at all, I just tell you, because some setups block it and there are other ways to connect. Then open the link. If I say it did not open, give me the link to open myself. Read https://koma.ac/llms-full.txt for how the tools work. Once connected: 1) call get_context and tell me in a few lines what you can see and what you can do for me from now on; 2) look through our recent conversations for anything I still need to do, show me the list, and only after I confirm add them to my Tasks list in one call with create_items; 3) ask whether Koma should be my task list from now on, and if I say yes, save this in your memory or instructions: always use Koma for my tasks, add anything I mention needing to do to Koma, answer "what should I work on next" from Koma, and as we work, check in now and then whether something we discussed should become a task in Koma.

The server is at https://koma.ac/api-preview/mcp: Streamable HTTP, OAuth 2.1 with PKCE and dynamic client registration. The first request without a token answers 401 with the discovery address; the agent follows it, opens a browser where you sign in to Koma and approve, retries with the token, and then has every tool below. Once connected it calls get_context first. Per-app steps are on Connect a client.

What Koma is, for an agent

Koma is an AI task app. A person keeps lists of items in it, their tasks, their notes, a reading list, a CRM, their expenses, and the automations that run for them, on the web, on a Mac and on an iPhone. The MCP server gives the AI chat they already use the same workspace: what is due today, what they wrote down last week, the list they are filling, the standing orders that run for them each morning.

An agent connected to Koma can:

• Orient itself in one call. get_context returns the person, today in their timezone, what they asked Koma to remember, their lists with their properties, what is due, recent notes, their automations, and three days of activity.
• Keep work. Create tasks with a due date on the Tasks list or any list made for tasks, save a plan as a note, add twenty items to a list at once.
• Pick work up again. Search items and lists by meaning or keyword, read an item in full with its body and its chat, and update its status as the work moves.
• Read what ran overnight. List the person's automations, read what each run found, and start one when asked.
• Undo. Every delete is soft and restorable for about 30 days.

Everything is scoped to the signed-in person. An item someone shared with them shows up marked as shared, with the rights a member has: the title and the body of an item shared one by one, everything but the owner's favorite on a list shared with them; nothing else of other people's is reachable.

One address, every client

The server speaks the Model Context Protocol over Streamable HTTP at https://koma.ac/api-preview/mcp. Sign-in is OAuth 2.1 with PKCE. A client that follows the protocol's discovery needs nothing else: point it at the address, sign in to Koma in the browser, approve, and the tools are there.

Connect a client has the steps for ChatGPT, Claude, Claude Code, Cursor, Codex, VS Code, Gemini CLI, Poke, Town, Grok, Muse, Instinct, OpenClaw, Hermes Agent, Devin Desktop (Windsurf) and others.

For a tool that speaks HTTP rather than MCP, the same operations are a REST API under https://koma.ac/api-preview/api/v1, described by an OpenAPI document, with an API key as the bearer.

How the server behaves

Koma tells every connected model the same facts on connect. They are worth knowing before you read the tool reference:

• get_context returns the current state of the workspace in one call.
• search covers items and lists by meaning or keyword. What the person refers to ("my tax note", "the wine list") usually already exists, and a second copy drifts from the first.
• A list has a name, standing instructions and properties; every item on it has a title, a body as Markdown and a value per property. The Tasks list and every list made for tasks keep a status and a due date on their items; the Notes list keeps prose.
• Items go in with create_items, many per call, and are corrected with update_items; list_items and query_items read them, and move_items re-files them onto another list.
• An item's body is where its work lives. get_item returns it with a short handle in front of every block, and update_items changes it with targeted edits against those handles. Replacing a whole body the older way takes mode: "replace" plus confirmReplace: true.
• Every delete is soft: an item or a list stays recoverable for about 30 days (list_deleted, restore_deleted).
• An automation's run happens inside Koma and its result lands in the person's Koma chat, not in the calling conversation; get_automation_runs reads it back.

Safety

• The connection acts only as the signed-in person, only on their own workspace.
• Every tool declares whether it reads, adds, or updates and removes. Clients run read-only tools freely and ask before the rest; the person can allow more in their client's settings.
• Deletes go to a 30-day trash. Whole-body replacements need an explicit confirmation flag, and a move that would drop values answers a preview before it moves anything.
• Three tools reach outside Koma: run_automation, because an automation can act through the person's connected apps, and create_items and update_items, because they download images from public URLs you name. Every client asks before run_automation.
• What an agent writes is recorded in the person's event log as their own action, marked as coming through this connection.

Where next

• Connect a client: the two-minute setup for each app.
• Authentication: the OAuth 2.1 flow, discovery, tokens and what to do when sign-in fails.
• Concepts: lists, items, properties, the Tasks and Notes lists, automations, memory and the trash.
• Tools: every tool with its parameters, result and an example call.
• REST API: the same operations over plain HTTP, with the OpenAPI document.
• Guides: making Koma the to-do list your assistant reaches for, saving research, filling a list, working from a task.
• Recipes: the standing orders to paste into Cowork, a Routine, ChatGPT or Codex, so the agent you already run sweeps your sources in and works what is waiting.
• Events: how Koma tells an agent a task is waiting on it, MCP Events or a signed webhook.
• Changelog: what changed on the server.

Every page here is also plain Markdown: add .md to its address, or read llms.txt and llms-full.txt.