Roma for the AI chat you already use.

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, Claude Code, Cursor, Codex, VS Code, Poke, Town, 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.