Connect a client

Connecting your own agent, not building a client? Agents has the short version, one page per app, with the same steps as here.

The address is the same everywhere: https://koma.ac/api-preview/mcp. You need a Koma account; the first connection opens a browser where you sign in to Koma and approve the app. Nothing is pasted, no key is copied.

Every client below speaks the Model Context Protocol over Streamable HTTP with OAuth 2.1, which is all the server needs. If yours is not listed, point it at the address and it will most likely work; authentication says what it has to support.

To check any connection, ask: "What's on my plate today in Koma?" The answer should use your own task titles.

ChatGPT

ChatGPT connects a custom MCP server through Developer mode, on Pro, Plus, Business, Enterprise and Education accounts on the web; a Business, Enterprise or Education workspace can turn it off or limit it.

  1. Open Settings, then Security and login, and turn on Developer mode.
  2. On the web, open Plugins (chatgpt.com/plugins), press the plus button, then Add custom MCP server. Name it Koma, give it a short description, enter the server address https://koma.ac/api-preview/mcp, keep OAuth, accept the notice ("I understand and want to continue"), press Create as a plugin and sign in to Koma when asked. It then sits under Installed.
  3. Use it in a Work chat: on the ChatGPT home switch the tab from Chat to Work, type @ and pick Koma, then ask. A chat keeps the tool list it started with, so start a new one after installing.

Add it on the web, not in the desktop app. The desktop app's MCP form writes the server into Codex's local config: a plugin made from it runs only on that computer, does not appear in a Work chat on the web, and cannot subscribe to Koma's events. A server added on the web is on your account and works in the desktop app too.

Good to know

Ask for it by name ("@Koma, what's due today?") or just ask about your tasks. ChatGPT confirms before a tool changes anything; you can tell it to remember your choice for that tool for the rest of the conversation, and a new conversation asks again. ChatGPT remembers the sign-in for a server address, so an app removed and added again comes back on the same Koma account; to switch accounts, disconnect it first.

Claude

Connect Koma once on claude.ai and it is available everywhere you are signed in: Claude Desktop, Claude on your phone, Cowork and Claude Code.

  1. Open Customize, then Connectors, then Add, then Add custom connector.
  2. Name it Koma, paste https://koma.ac/api-preview/mcp, leave sign-in on, and add it.
  3. Choose Connect, sign in to Koma, and approve.

Good to know

A Free account can add one custom connector; the paid plans add as many as you like. On a Team or Enterprise plan an owner adds Koma under Organization settings, then Connectors, then Add, then Custom, then Web; each member then finds it under Customize, then Connectors, and chooses Connect.

In a conversation, Koma is on under the plus menu's Connectors. The first time a tool runs, Claude asks and offers Allow always for that tool, so the writes can be allowed once and never asked about again. On a Team or Enterprise plan an owner can also set each tool to Always allow, Needs approval or Blocked under Organization settings, then Connectors, then Koma, then Tool permissions.

Claude Code

bash
claude mcp add --transport http koma https://koma.ac/api-preview/mcp

Then run /mcp inside Claude Code and choose Koma to sign in.

Good to know

Add --scope user to keep the server across every project. A connector added on claude.ai shows up here too. When Koma adds a tool, Claude Code picks it up in the running session.

Cursor

Use the one-click link, Add Koma to Cursor, or add this to ~/.cursor/mcp.json (or the project's .cursor/mcp.json) and sign in when Cursor asks:

json
{
  "mcpServers": {
    "koma": { "url": "https://koma.ac/api-preview/mcp" }
  }
}

Codex

bash
codex mcp add koma --url https://koma.ac/api-preview/mcp
codex mcp login koma

The login opens the browser for the sign-in.

Good to know

The same entry serves the Codex CLI, the IDE extension and Codex in the ChatGPT desktop app (there: Settings, then MCP servers, then Add server, Streamable HTTP, the address, a restart of the app, then Authenticate). By hand it is [mcp_servers.koma] with url = "https://koma.ac/api-preview/mcp" in ~/.codex/config.toml. A standing line in ~/.codex/AGENTS.md, such as "use Koma for my tasks", holds across every project.

VS Code

Use the install link, Add Koma to VS Code, or from a terminal:

bash
code --add-mcp '{"name":"koma","type":"http","url":"https://koma.ac/api-preview/mcp"}'

Confirm the trust prompt, then sign in in the browser VS Code opens on the first connection.

Good to know

The equivalent .vscode/mcp.json:

json
{
  "servers": {
    "koma": { "type": "http", "url": "https://koma.ac/api-preview/mcp" }
  }
}

Gemini CLI

bash
gemini mcp add --transport http koma https://koma.ac/api-preview/mcp

Then /mcp auth koma inside the CLI to sign in.

Good to know

The gemini command serves organizations on Gemini Code Assist Standard or Enterprise and paid Gemini API keys; individual Google accounts were moved to Antigravity CLI in June 2026. On Antigravity, add Koma with npx add-mcp (under Other clients below), which writes it into its config.

Poke

At poke.com/integrations/new, add Koma with the address https://koma.ac/api-preview/mcp. Leave the key field empty to sign in with OAuth, or paste an API key from Settings, then Connections.

Good to know

From a terminal:

bash
npx poke@latest mcp add https://koma.ac/api-preview/mcp -n "Koma"

Mention Koma by name, or what you want it to do, so Poke knows to use it.

Town

Open Settings, then MCP, then Add Server, and enter a name, the address https://koma.ac/api-preview/mcp and a short description. Town runs the sign-in itself.

Grok

At grok.com/connectors, choose New Connector, then Custom, and enter the address https://koma.ac/api-preview/mcp. Complete the sign-in when Grok asks. On Grok Business or Enterprise a team admin adds the connector first.

Muse

Muse has no settings screen for this; you ask it in the conversation, and the prompt on its page does. The short form:

Create a Custom Connector for a remote MCP server. URL: https://koma.ac/api-preview/mcp. Auth: OAuth.

  1. Paste the prompt into Muse. It creates the connector on its own cloud computer and shows a Connect button.
  2. Press Connect, sign in to Koma, and approve.
  3. Muse confirms, keeps the connector in its Secure Credentials Store for next time, and asks whether Koma should be its to-do list. Say yes.

Good to know

If the sign-in window does not open at all when you press Connect, some setups block it; tell Muse, and it gives you the link to open yourself. If the page after you approve shows a link to copy, paste it to Muse. If Muse asks for a key instead, create one in Koma under Settings, then Connections, and paste it only into Muse's secure credential prompt, never into the chat itself.

Muse Code, the terminal agent, takes the server in ~/.config/muse/settings.json:

json
{
  "schema_version": 1,
  "mcp_servers": {
    "koma": { "transport": "streamable_http", "url": "https://koma.ac/api-preview/mcp" }
  }
}

Then muse mcp login koma for the sign-in. It reads an AGENTS.md, where a standing line like "use Koma for my tasks" lives.

Instinct

Instinct lives in your messages, so there is no settings screen; the prompt on its page is the whole setup. It walks Instinct through the sign-in as four web requests, the way Instinct connects to any web service.

  1. Send Instinct the prompt. It registers itself with Koma and replies with a sign-in link.
  2. Open the link, sign in to Koma, and approve.
  3. Koma shows a link to send back. Paste it to Instinct within ten minutes; the sign-in expires after that.
  4. Instinct confirms, tells you what it sees, and asks whether Koma should be its to-do list. Say yes.

Good to know

Instinct is invite-only while in beta, and it has no connector for MCP servers of its own yet. The prompt walks it through the four OAuth steps as web requests, the way one Instinct described its own connection ("I generate an authorization link, you approve, you send me the callback URL, I exchange it for a token"); asked to "build an MCP client" instead, an Instinct refused. If yours still declines, try the key instead: in Koma open Settings, then Connections, press Create key, and text Instinct the key with "use Koma's REST API at https://koma.ac/api-preview/api/v1 with this as the bearer token; the reference is at https://koma.ac/llms-full.txt". Those are plain web requests, which Instinct makes without building anything. The key acts as you, so share it only with an assistant you trust and revoke it in the same place when done. If it declines that too, ask it for a paste-ready list of your open items and add them in Koma. If the link expired, Instinct starts a fresh one; if it says the connection lapsed later, send the prompt again and approve once more.

OpenClaw

bash
openclaw mcp add koma --url https://koma.ac/api-preview/mcp --transport streamable-http
openclaw mcp login koma

Good to know

openclaw mcp doctor koma --probe checks the connection. The login opens a browser where OpenClaw can reach one; otherwise copy the code the sign-in page shows and run openclaw mcp login koma --code <code>.

Hermes Agent

In ~/.hermes/config.yaml, add the server under mcp_servers, then sign in from the terminal:

yaml
mcp_servers:
  koma:
    url: "https://koma.ac/api-preview/mcp"
    auth: oauth
bash
hermes mcp login koma

Good to know

Add the server and sign in before you start a session: Hermes connects to its servers when it starts, a running session keeps its tools until /reload-mcp or /new, and its own reload gives a sign-in only thirty seconds, so run the login from a terminal of its own. The login opens a browser; on a machine without one, copy the address the browser ends up on and paste it back into the terminal where Hermes asks for it. A sign-in started from Hermes Desktop's MCP setup completes on its own. Koma's tools appear as mcp__koma__<tool>, so mcp__koma__get_context; hermes mcp test koma shows what the server answered. For a key instead of the sign-in (a gateway with no browser), replace auth: oauth with headers: { Authorization: "Bearer koma_…" }.

Devin Desktop (Windsurf)

In ~/.config/devin/mcp_config.json, add a server with "serverUrl": "https://koma.ac/api-preview/mcp" under mcpServers, named koma, or add a custom server from the MCP list in Devin Local. The sign-in runs when the server first needs it; an expired one shows Authenticate in that list.

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth works. Add the server with the address https://koma.ac/api-preview/mcp and no headers; the client discovers the sign-in from the server's first 401 answer. If a client offers to enter a client id and secret by hand, leave them empty: the server registers clients dynamically.

An agent with no place to add a server, one that lives in your messages or on a cloud computer of its own, connects from the prompt on the any-agent page all the same: four web requests, nothing installed. It registers itself at the discovery address with a loopback return address, sends you the sign-in link, you approve and paste back the link the browser lands on within ten minutes, and it exchanges the code for a token. Authentication has the flow in full.

Every coding agent on the computer at once, with add-mcp (it finds Claude Code, Codex, Cursor, VS Code, Gemini CLI, Windsurf and more, and writes Koma into each one's config; each agent runs its own sign-in the first time it connects):

bash
npx add-mcp https://koma.ac/api-preview/mcp -n koma

Without a browser: an API key

A scheduled job, a self-hosted agent or a client that only takes a pasted key connects with an API key instead of signing in. In Koma, open Settings, then Connections, press Create key at the bottom, and copy it once. Then send it as the bearer token:

bash
claude mcp add --transport http koma https://koma.ac/api-preview/mcp --header "Authorization: Bearer koma_…"

The key acts as you on your own workspace, so keep it as private as a password and revoke it in the same place when the agent no longer needs it. Authentication has the details.

Get the most out of it

The Agents page has the one message that makes Koma your agent's to-do list in a conversation. For a standing line that holds across every conversation, add this to your chat's custom instructions (or a Claude project's instructions), so each one starts from where you are:

Koma is my task app. At the start of a conversation about my work, plans or anything I keep, call Koma's get_context to see my tasks, notes and what I asked it to remember. When I mention something I need to do, add it to Koma as a task. When I ask what to work on next or what is on my plate, answer from Koma.

Then try:

  • "What's on my plate today?"
  • "Save the plan we just made as a note."
  • "Add these five books to my reading list."
  • "What did my morning briefing find today?"
  • "Mark the dentist task done and remind me about the invoice on Friday."

Disconnect

Remove Koma in your chat app's settings. That deletes the token the app holds. To have the grant revoked on our side too, email hello@koma.ac. Signing out of the Koma web app does not disconnect an AI app, and disconnecting an AI app does not sign you out of Koma.