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://api.roma.app/mcp. You need a Roma account; the first connection opens a browser where you sign in to Roma 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 Roma?" The answer should use your own task titles.

ChatGPT

Without the directory listing, add Roma as a custom MCP server on the web, the same three steps Settings → Agents shows:

  1. Add Roma to ChatGPT. On chatgpt.com open Plugins (chatgpt.com/plugins), press the plus button, then Add custom MCP server. Name it Roma, paste https://api.roma.app/mcp as the Server URL, keep OAuth, tick I understand and want to continue and press Create as a plugin. Then press Connect Roma and Approve on the Roma page that opens; the plugin stands under Plugins, Personal. Press Refresh tools once (the plugin, Manage, Refresh tools). On the web, not in the Mac app: a server added through the Mac app's own form runs on that Mac alone. ChatGPT is one of your agents the moment it is connected.
  2. Save instructions in ChatGPT. Paste the message under Settings → Personalization → Custom instructions. From then on ChatGPT keeps your to-dos in Roma.
  3. Let Roma notify ChatGPT. Optional. In Roma open Settings, then Agents, then ChatGPT. Send the message the page gives you in a Work chat. ChatGPT then hears about each task you delegate to it and each reply.

Added once on the web, Roma is on your ChatGPT account: the Mac app with Cloud selected and the phone see it too.

Good to know

Use it in a Work chat: on the ChatGPT home switch the tab from Chat to Work, type @ and pick Roma, then ask. A chat keeps the tool list it started with, so start a new one after installing. The plugin is on every plan. A custom MCP server added by hand is for Business, Enterprise and Education accounts on the web; Pro can connect one with read permissions only. A Business, Enterprise or Education workspace can turn plugins off or limit them. 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 Roma account; to switch accounts, disconnect it first.

ChatGPT is one of your agents the moment it is connected: open Settings → Agents in Roma and it is there. To hand it work, pick ChatGPT as an item's delegate. Follow the steps on its page to let Roma wake ChatGPT when you delegate an item to it or reply to its post.

Claude

Connect Roma 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 Roma, paste https://api.roma.app/mcp, leave sign-in on, and add it.
  3. Choose Connect, sign in to Roma, 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 Roma 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, Roma 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 Roma, then Tool permissions.

Roma hands Claude the items you delegate to it through a scheduled task Roma fires the moment you delegate an item or reply to Claude's post. You create the task once at claude.ai/code/routines with an API trigger: no repository is needed, and it is on every paid plan. Settings → Agents gives you the task's prompt and takes its Fire URL and token. Each run is a fresh Claude session with your connectors, so the item's body and chat are its memory. If you would rather not create the trigger, an hourly task of Claude's own reads what is delegated to it instead, hourly at the fastest.

Claude is one of your agents the moment it is connected: open Settings → Agents in Roma and it is there. To hand it work, pick Claude as an item's delegate. Follow the steps on its page to let Roma wake Claude when you delegate an item to it or reply to its post.

Claude Code

The plugin brings the Roma server and the skill that teaches Claude Code when to reach for it, in one install:

bash
claude plugin marketplace add tobyshi/roma-claude-plugin
claude plugin install roma@roma

Then run /mcp inside Claude Code, choose roma and sign in.

To add only the server, without the skill:

bash
claude mcp add --scope user --transport http roma https://api.roma.app/mcp

Good to know

The plugin does not update itself: run claude plugin update roma@roma when Roma ships a new version, or turn on auto-update for the roma marketplace under /plugin, then Marketplaces. The command adds Roma for every folder, not only the one you ran it in. A connector added on claude.ai shows up in Claude Code too, without the skill. When Roma adds a tool, Claude Code picks it up in the running session.

Claude Code is one of your agents the moment its sign-in lands: open Settings → Agents in Roma and it is there. To hand it work, pick Claude Code as an item's delegate. To let Roma wake Claude Code on your computer, send it the sentence from its page again. Claude Code sets up Roma Bridge. You press Approve once. Your computer runs Claude Code while it is awake. How Roma Bridge works.

Cursor

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

json
{
  "mcpServers": {
    "roma": { "url": "https://api.roma.app/mcp" }
  }
}

Codex

ChatGPT and Codex share one plugin directory. Add Roma in ChatGPT's plugins, sign in and approve once, and it is in Codex in the ChatGPT desktop app (type @ and pick Roma) and in the Codex CLI (/plugins shows it on; a new session has it), the server and the skill together.

Without the plugin, the server alone, one command:

bash
codex mcp add roma --url https://api.roma.app/mcp

It opens the browser for the sign-in. If no browser opens, run codex mcp login roma.

Good to know

The server entry, with or without the plugin, serves the Codex CLI and Codex in the ChatGPT desktop app; the IDE extension takes the server but not the plugin. By hand it is [mcp_servers.roma] with url = "https://api.roma.app/mcp" in ~/.codex/config.toml. A standing line in ~/.codex/AGENTS.md, such as "use Roma for my tasks", holds across every project.

Codex is one of your agents the moment its sign-in lands: open Settings → Agents in Roma and it is there. To hand it work, pick Codex as an item's delegate. To let Roma wake Codex on your computer, send it the sentence from its page again. Codex sets up Roma Bridge. You press Approve once. Your computer runs Codex while it is awake. How Roma Bridge works.

VS Code

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

bash
code --add-mcp '{"name":"roma","type":"http","url":"https://api.roma.app/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": {
    "roma": { "type": "http", "url": "https://api.roma.app/mcp" }
  }
}

Gemini CLI

bash
gemini mcp add --transport http roma https://api.roma.app/mcp

Then /mcp auth roma 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 Roma with npx add-mcp (on the any agent page), which writes it into its config.

Poke

At poke.com/integrations/new, add Roma with the address https://api.roma.app/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://api.roma.app/mcp -n "Roma"

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

To delegate work to Poke, open Settings → Agents in Roma, tap Poke, and follow the steps on its page. Paste what that page gives you, nothing from here; Roma then wakes Poke when you delegate an item to it or reply to its post.

Town

Open Integrations in Town's sidebar, then Custom Integrations (MCP), press Add an integration and enter the address https://api.roma.app/mcp. Town runs the sign-in itself.

Good to know

Each Townie has an inbox of its own at town.com; Roma mails it. Town's routines can also start from a webhook (the routine's Advanced settings, Enable webhook), a second door Roma does not use yet.

To delegate work to Town, open Settings → Agents in Roma, tap Town, and follow the steps on its page. Paste what that page gives you, nothing from here; Roma then wakes Town when you delegate an item to it or reply to its post.

Grok

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

Good to know

Grok is one of your agents the moment it is connected: open Settings → Agents in Roma and it is there. To hand it work, pick Grok as an item's delegate. Follow the steps on its page to let Roma wake Grok when you delegate an item to it or reply to its post.

Grok Bot

Grok Bot is xAI's always-on Bot, a different app from Grok the chat. It has no settings screen for a server of your own: in the Bot's chat, send it https://api.roma.app/mcp and ask it to add Roma as a custom MCP server. It shows a card to confirm, then a Connect card: press it and sign in to Roma. The Bot signs in with OAuth; a key would go into a masked field it opens, never into the chat.

Good to know

A Bot keeps its own instructions and memory, so tell it once how you want Roma used. Its routines can start from a webhook: open the routine in the desktop app (the phone apps do not show this yet) and its Webhook section shows the address to POST to and the key, which the Bot itself never sees; a 200 means a run started, and the run can use Roma's tools. The Bot can claim a mail inbox of its own, the name permanent once claimed, and a routine can wake on mail to it; mail a routine sends always waits as a draft until you press Send. A rule under Custom Rules (Settings, then General, then Bot, under Auto-review) lets a routine use Roma's tools without asking you each time. That is the road Roma wakes it on for the items you delegate to it.

To delegate work to Grok Bot, open Settings → Agents in Roma, tap Grok Bot, and follow the steps on its page. Paste what that page gives you, nothing from here; Roma then wakes Grok Bot when you delegate an item to it or reply to its post.

Muse

Muse has no settings screen for this; you ask it in the conversation. Send it the message on its page: Muse reads how to connect and creates a Custom Connector for the server on its own cloud computer and signs you in once. If its sign-in is ever gone, a Roma key from its page in Settings is the backup: Muse keeps it in its vault and connects with it instead. To say it yourself instead:

Create a Custom Connector for a remote MCP server. URL: https://api.roma.app/mcp. Auth: OAuth.

  1. Send Muse the message. It creates the connector and shows a Connect button.
  2. Press Connect, sign in to Roma, and approve.
  3. Muse confirms, keeps the connector in its Secure Credentials Store for next time, and tells you what it sees.

Good to know

If the sign-in window does not open at all when you press Connect, Safari is the usual reason (it refuses the window Muse opens first and fills later), and a pop-up or ad blocker does the same; tell Muse it did not open and ask for the sign-in link as plain text, then open it in a tab of your own. If the page after you approve shows a link to copy, paste it to Muse. If Muse's sign-in is ever gone, for example after Sign out everywhere in Roma, make a key under Settings on Muse's page in Roma and paste it only into Muse's credential card, never into the chat itself; Muse keeps it in its vault and connects with it instead.

Muse has no webhook. It can watch an address of its own instead. A hook Muse makes peeks at a public signal address every few seconds, with no login, and wakes Muse when a marker there moves. Muse then reads the item through its signed-in connection. That is how Muse hears about new work quickly. A task of Muse's own reads Roma every five minutes as well.

Under Settings → Agents the setup is one message. Muse connects from it, then makes two things of its own. A hook named Listen to Roma checks a signal address every 10 seconds. The address is public and needs no login. It answers only whether something is new, and nothing private is in it. When something is new, the hook wakes Muse, and Muse reads the item through its signed-in connection. So Roma wakes Muse within about 10 to 30 seconds of a delegation or a reply. A task named Check Roma reads Roma every five minutes as the floor, in case the hook misses something. The signal address is under Settings on Muse's page, with Copy.

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

json
{
  "schema_version": 1,
  "mcp_servers": {
    "roma": { "transport": "streamable_http", "url": "https://api.roma.app/mcp" }
  }
}

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

To delegate work to Muse, open Settings → Agents in Roma, tap Muse, and follow the steps on its page. Paste what that page gives you, nothing from here. Muse then reads what you delegate to it itself, within a few minutes.

Instinct

Instinct lives in your messages, so there is no settings screen; the message on its page is the whole setup. Instinct adds a remote MCP server over OAuth the way it reaches any web service: nothing installed, one approval in your browser, in one sitting.

  1. Send Instinct the message. It reads how to connect and sends you a link to approve.
  2. Open the link, sign in to Roma, and approve.
  3. After you approve, the browser lands on a page that may look broken: that is Instinct's own callback, not an error of Roma's. Copy the address from the address bar anyway and paste it back to Instinct within a few minutes; the approval expires after that, and a new link is one message away.
  4. Instinct confirms and tells you what it sees.

Good to know

Instinct is invite-only while in beta, and it has no connector screen for MCP servers, so whether it connects depends on the Instinct you have. Several have, by the steps above. Others decline, saying they cannot add an outside MCP server or hold a token, and one declined after reading the message as setup text pasted from Roma. What has worked then is a reply in your own words that describes the same approval the way an Instinct that connected described it. The Roma app gives you that reply under Settings, then Agents, then Instinct. If yours still declines, the key is the other way in: in Roma open Settings, then Connections, press Create key, and text Instinct the key with "use Roma's REST API at https://api.roma.app/api/v1 with this as the bearer token; the reference is at https://roma.app/developers/api.md". 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 Roma.

The sign-in does not last on its own. Instinct's vault is archival, so every rebuild of its environment drops the token. With a key of the record saved in that vault as a login for Roma's sign-in page, Instinct signs in again by itself: it opens a fresh approval link in its own browser, the vault fills in the key, and Instinct is connected again. Without the key, send the message once more and paste the address back.

Once connected, Instinct posts in a task's chat without asking. It edits a task's text only once you have allowed that, in one message, and keeps to it. A mail to anyone else it drafts for your approval, and a booking or a payment it always confirms with you first.

Under Settings → Agents the setup is one paste, one approval and one key. You text Instinct the page's message, approve the sign-in once, and save the key the page makes in Instinct's vault, as a login for Roma's sign-in page. From then on Instinct reads Roma every five minutes, on the clock, over its MCP server: the items newly delegated to it, and your replies to its posts, which each item reports to it. When nothing changed, it stays quiet. When a rebuild of its environment drops its sign-in, the next read fails and Instinct signs in again by itself with the key from its vault, so the connection heals before your next task. A mail can make it faster. Some Instincts have a mail address of their own, and a mail there wakes Instinct at once. The page's optional second step gives you a short message that asks Instinct for its address. Paste the address under Settings there. Roma then mails Instinct the moment you delegate a task to it or reply. Without an address nothing changes: the five-minute read does the work. Instinct has no public URL, so a webhook is not a road to it.

To delegate work to Instinct, open Settings → Agents in Roma, tap Instinct, and follow the steps on its page. Paste what that page gives you, nothing from here. Instinct then reads what you delegate to it itself, within a few minutes.

OpenClaw

bash
openclaw mcp add roma --url https://api.roma.app/mcp --transport streamable-http
openclaw mcp login roma

Good to know

openclaw mcp doctor roma --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 roma --code <code>.

Hermes Agent

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

yaml
mcp_servers:
  roma:
    url: "https://api.roma.app/mcp"
    auth: oauth
bash
hermes mcp login roma

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 a reload never signs in, so run the login from a terminal of its own; it waits up to five minutes for the browser. On a machine without one, hermes mcp login roma --flow device gives a code instead. A sign-in started from Hermes Desktop's MCP setup completes on its own. Roma's tools appear as mcp_roma_<tool>, so mcp_roma_get_context; hermes mcp test roma shows what the server answered. A standing line in ~/.hermes/SOUL.md holds for every session. Hermes has no inbox of its own; mail reaches it through its AgentMail skill or the OpenMail plugin. For a key instead of the sign-in (a gateway with no browser), replace auth: oauth with headers: { Authorization: "Bearer roma_…" }.

To delegate work to Hermes, open Settings → Agents in Roma, tap Hermes, and follow the steps on its page. Paste what that page gives you, nothing from here; Roma then wakes Hermes when you delegate an item to it or reply to its post.

Devin Desktop (Windsurf)

In ~/.config/devin/mcp_config.json, add a server with "serverUrl": "https://api.roma.app/mcp" under mcpServers, named roma, 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://api.roma.app/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 all the same, from the message on the any-agent page: the sign-in is four web requests, nothing installed, listed as Option 3 on the overview. 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 Roma into each one's config; each agent runs its own sign-in the first time it connects):

bash
npx add-mcp https://api.roma.app/mcp -n roma

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 Roma, 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 --scope user --transport http roma https://api.roma.app/mcp --header "Authorization: Bearer roma_…"

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.

What can go wrong

  • The sign-in window does not open. A pop-up blocker, a content blocker or an ad blocker in the browser stops it, and Safari refuses a window an app opens first and fills later (Muse's Connect button is the known case). Tell the agent it did not open and ask for the sign-in link as plain text, then open it in a tab of your own.
  • The page after approving does not load. "This site can't be reached" at 127.0.0.1 means the agent runs in the cloud and nothing listens at the address it gave. Roma's connected page, the one right after Approve, has the link to copy and stays put when nothing answers; if the browser moved on anyway, go back one page. Paste the link to the agent within ten minutes.
  • The link expired. A sign-in link is good for ten minutes. Ask the agent for a fresh one.
  • You were signed out. The sign-in page brings you back to the approval once you are in.
  • The agent says it cannot run that, or that the text looks like setup instructions. It is reading the message as something to execute rather than as your wish. Say it in your own words: you use Roma for your tasks and want it connected, the ways to connect are explained at https://roma.app/agents.md, and it should tell you what it will do first. The Instinct page has a reply written for exactly this. An agent that would rather not connect at all can still help: ask it for a paste-ready list of your open items and add them in Roma by hand.
  • It worked, then stopped an hour later. The access token lasts an hour and the agent renews it with its refresh token. An agent that keeps no token between conversations has to sign in again, or takes an API key instead, which does not expire.
  • A tool is missing. The client cached an older tool list. Refresh the connector in the client and start a new conversation.

Get the most out of it

The Agents page has the one message that makes Roma 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:

Roma is my task app. At the start of a conversation about my work, plans or anything I keep, call Roma'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 Roma as a task. When I ask what to work on next or what is on my plate, answer from Roma.

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 Roma in your chat app's settings. That deletes the token the app holds. To have the grant revoked on our side too, email hello@roma.app. Signing out of the Roma web app does not disconnect an AI app, and disconnecting an AI app does not sign you out of Roma.