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

Connect in one step

Paste this into your agent, whichever one you use:

Connect to Roma, my task app, as an MCP server at https://api.roma.app/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, use it rather than writing a client of your own (Muse: create a Custom Connector for a remote MCP server with that URL and Auth: OAuth; Codex: codex mcp add roma --url https://api.roma.app/mcp, then codex mcp login roma). 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. Then open the link. Read https://roma.app/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 in one call with create_tasks; 3) ask whether Roma should be my task list from now on, and if I say yes, save this in your memory or instructions: always use Roma for my tasks, add anything I mention needing to do to Roma, answer "what should I work on next" from Roma, and as we work, check in now and then whether something we discussed should become a task in Roma.

The server is at https://api.roma.app/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 Roma 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 Roma is, for an agent

Roma is an AI task app. A person keeps their tasks, notes, projects, lists and automations in it, 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 Roma can:

• Orient itself in one call. get_context returns the person, today in their timezone, what they asked Roma to remember, their projects, what is due, recent notes, their lists and automations, and three days of activity.
• Keep work. Create tasks with a due date and a project, save a plan as a note, add twenty rows to a list at once.
• Pick work up again. Search notes, tasks and list rows by meaning or keyword, read a task with its subtasks, 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 and private to them. There is no shared or team data on this surface.

One address, every client

The server speaks the Model Context Protocol over Streamable HTTP at https://api.roma.app/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 Roma in the browser, approve, and the tools are there.

Connect a client has the steps for ChatGPT, Claude, Codex, Muse, Claude Code, Cursor, VS Code, Gemini CLI, Town, Poke, Grok and others.

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

How the server behaves

Roma tells every connected model the same eight 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 notes, tasks, lists and list rows 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 note is prose; a collection is a table. Rows go in with add_collection_items and are corrected with update_collection_items, many rows per call.
• update_note and update_task append to the body by default. Replacing a whole body takes mode: "replace" plus confirmReplace: true.
• Every delete is soft: an item stays recoverable for about 30 days (list_deleted, restore_deleted).
• An automation's run happens inside Roma and its result lands in the person's Roma 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.
• Three tools reach outside Roma: run_automation, because an automation can act through the person's connected apps, and the two row tools, 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: tasks, notes, projects, collections, 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 Roma the list your assistant reaches for, saving research, working from a task.
• 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.