# Roma for developers and agents

Connect the AI chat you already use to Roma through its MCP server: one address, OAuth 2.1, 29 tools over tasks, notes, projects, lists and automations.

## 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](/developers/connect) 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](/developers/api) under `https://api.roma.app/api/v1`, described by an OpenAPI document, with an [API key](/developers/authentication#api-keys) 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](/developers/connect): the two-minute setup for each app.
- [Authentication](/developers/authentication): the OAuth 2.1 flow, discovery, tokens and what to do when sign-in fails.
- [Concepts](/developers/concepts): tasks, notes, projects, collections, automations, memory and the trash.
- [Tools](/developers/tools): every tool with its parameters, result and an example call.
- [REST API](/developers/api): the same operations over plain HTTP, with the OpenAPI document.
- [Guides](/developers/guides): making Roma the list your assistant reaches for, saving research, working from a task.
- [Changelog](/developers/changelog): what changed on the server.

Every page here is also plain Markdown: add `.md` to its address, or read [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt).