Connect a client

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

ChatGPT connects a custom MCP server through Developer mode. Which plans can add one, and whether it may make changes or only read, depends on your plan and your workspace's settings.

  1. Open Settings, then Security and login, and turn on Developer mode.
  2. Go to chatgpt.com/plugins, choose the plus, and enter a name (Roma), a short description and the server address https://api.roma.app/mcp. Choose OAuth.
  3. Sign in to Roma and approve. Then start a new chat: an existing conversation keeps the tool list it started with.

Ask for Roma by name in a message (@Roma) or just ask about your tasks. ChatGPT confirms before a tool changes anything; the plugin's permission setting lets you relax that.

Claude

Claude.ai, Claude Desktop and Claude on your phone share one connector list; a connector added on the web is available everywhere you are signed in, including Claude Code and Cowork.

  1. Open Customize (or Settings), then Connectors, then Add custom connector.
  2. Name it Roma, paste https://api.roma.app/mcp, and add it.
  3. Choose Connect, sign in to Roma, and approve.

On a Team or Enterprise plan an owner adds the connector under Organization settings, then Connectors, and members connect their own account.

In a conversation, Roma is on under the plus menu's Connectors. Under Customize, then Connectors, each tool can be set to Always allow, Needs approval or Blocked; read-only tools run without asking by default.

Claude Code

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

Then run /mcp inside Claude Code and choose Roma to sign in. Add --scope user to keep the server across every project. Claude Code lists the tools again at the start of every session, so a new tool appears next session.

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

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

The login opens the browser for the sign-in. The same entry serves the Codex CLI and the Codex app inside ChatGPT's desktop app.

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"}'

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.

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. From a terminal:

bash
npx poke@latest mcp add https://api.roma.app/mcp -n "Roma"

Mention Roma by name in a message the first time so Poke reaches for it.

Town

Open Settings, then MCP, then Add Server, and enter a name and the address https://api.roma.app/mcp. Town runs the sign-in itself.

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. Connectors are available on Grok's paid tiers.

OpenClaw

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

openclaw mcp doctor roma --probe checks the connection. The login uses a browser where OpenClaw can open one and a pasted code where it cannot.

Zed

Open Settings, then AI, then MCP Servers, then Add Remote Server, and enter the address. Or in settings.json:

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

Zed asks for the sign-in when the server has no header.

Devin Desktop (Windsurf)

In ~/.config/devin/mcp_config.json, add a server with "serverUrl": "https://api.roma.app/mcp" under mcpServers, named roma.

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.

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 --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.

Get the most out of it

Add one line to your chat's custom instructions (or a Claude project's instructions), so every conversation starts from where you are:

At the start of a conversation about my work, plans or anything I keep, use Roma's get_context to see my tasks, notes and what I asked it to remember. Save tasks and notes to Roma when I ask.

Then try:

  • "What's on my plate today?"
  • "Save the plan we just made as a note in my Trip project."
  • "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.