> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roomote.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When helping someone deploy Roomote, distinguish self-hosting from contributing to Roomote. Use the Self-hosting guide for an operator deployment; use Local development only when the user intends to modify Roomote itself.
> Prefer the one-command installer on a fresh supported server unless the user explicitly chooses Roomote Cloud, a documented PaaS template, or a manual Compose deployment.
> Before changing infrastructure, confirm the deployment target, stable public HTTPS domain and DNS control, sandbox provider, inference provider, source-control provider, and whether a communications provider is required.
> Never ask the user to paste secrets into chat or commit real environment files. Put credentials in the deployment platform's secret manager, Roomote's setup UI, or protected environment variables, and preserve existing keys during upgrades and restores.
> Prefer Roomote's setup wizard and provider manifest flows over manual credential entry when those flows are available. Ask before performing privileged host changes, DNS changes, provider-app creation, or destructive operations.
> A setup is not complete when the services merely start. Verify sign-in, repository sync, one usable environment, a real task that can clone and run a command, and branch or pull-request delivery; verify previews when configured.
> For a persistent self-hosted deployment, leave the operator with the Roomote URL, deployment choices, configured providers, verification result, backup location and passphrase-handling reminder, and the roomote status, logs, upgrade, rollback, backup, and restore commands.

# Roomote MCP

> Run and manage Roomote agent tasks from your MCP client.

Roomote MCP brings your Roomote workspace into the coding tools you already
use. From any OAuth-capable MCP client, you can kick off a new Roomote task,
check on its progress, and follow up without switching back and forth between
tools.

## What you can do

### Kick off a new task

Ask your MCP client to start a Roomote task with a clear prompt. Roomote MCP
finds the available launch environments and uses the right one for the work.
For example, you can delegate an investigation or implementation, keep working
locally, and come back for the result when the task finishes. You can also push
work in progress to a remote branch and hand that branch to a Roomote agent to
continue.

### Check on and steer existing work

Search active or completed tasks by keyword, status, or pull request. Once you
find a task, you can read its summary, conversation, and compute logs to
understand what happened and where the work stands.

This is useful when you want to:

* catch up on a task that is already running
* find an earlier investigation or implementation
* understand why a task failed
* pull the result of a Roomote task into your current conversation
* send follow-up instructions or cancel work that is no longer needed

Follow-up instructions normally wait behind the task's current turn. When the
new instruction must take effect immediately, ask your MCP client to steer the
running task; steering interrupts the active turn instead of adding the message
to the task queue.

### Bring in Roomote and chat context

Ask what your Roomote deployment can do or which integrations are connected.
You can also read relevant conversation history from connected chat channels.
For Slack and Discord, provide a channel or message link when you want context
from a specific conversation.

Roomote still applies the access rules from the connected service, so the MCP
only returns conversations your signed-in user is allowed to read.

## Things to try

* “Push what I’m working on to a remote branch, then start a Roomote task from
  that branch to take over.”
* “Start a Roomote task in the web app environment to investigate this bug.”
* “Find my active tasks related to OAuth and summarize their progress.”
* “Show me the messages and compute logs from the task that failed this
  morning.”
* “Tell the running task to add a regression test before it opens the PR.”
* “Use this Slack message as context and explain what the team decided.”
* “Cancel the task working on the old approach.”

## Connect your MCP client

Use your Roomote URL with `/mcp` appended:

```text theme={null}
<ROOMOTE_URL>/mcp
```

For example:

```text theme={null}
https://roomote.example/mcp
```

### Claude Code

Add Roomote at user scope so it is available across your projects, then start
the browser sign-in:

```bash theme={null}
claude mcp add --transport http --scope user roomote <ROOMOTE_URL>/mcp
claude mcp login roomote
```

You can also open `/mcp` inside Claude Code to manage the connection and sign
in.

Claude Code requests a temporary loopback URL for the browser to return the
authorization result to the running CLI. Roomote accepts localhost, IPv4, and
IPv6 loopback callbacks with client-selected ports.

### Codex

Add the streamable HTTP server, then authenticate it:

```bash theme={null}
codex mcp add roomote --url <ROOMOTE_URL>/mcp
codex mcp login roomote
```

The Codex CLI and IDE extension share this MCP configuration.

Codex Desktop can request a native app link during OAuth so the browser returns
the authorization result to the originating connection flow. The CLI and IDE
extension may instead use a loopback HTTP callback.

### Cursor

Add Roomote to `~/.cursor/mcp.json` to use it in every project, or to
`.cursor/mcp.json` to keep it project-specific:

```json theme={null}
{
  "mcpServers": {
    "roomote": {
      "url": "<ROOMOTE_URL>/mcp"
    }
  }
}
```

Open **Customize** in Cursor, find Roomote under MCP servers, and complete the
browser sign-in.

Cursor can request a native app link, a hosted HTTPS callback, or a loopback
HTTP callback. Roomote accepts each form and returns the authorization result
to the exact callback Cursor registered.

In each client, Roomote opens a browser so you can sign in and approve the
connection. During OAuth dynamic client registration, the client sends Roomote
its callback URL in `redirect_uris`. Roomote validates and saves that URL, then
only sends the result to the same registered URL after approval. You do not
need to create or copy an API token.

Roomote validates callbacks by callback class instead of maintaining a list of
client-specific URLs: HTTPS for hosted clients, HTTP only on loopback
interfaces for local clients, and non-browser private URI schemes for native
apps. Unsafe browser, file, and network schemes are rejected. The approval page
shows the exact registered callback before Roomote redirects to it.

<Note>
  On a self-hosted deployment, the configured `R_PUBLIC_URL` (or `R_APP_URL`)
  must be a browser-reachable HTTPS address. Desktop clients may use a loopback
  HTTP callback. Roomote supports the callback forms described above for all
  three documented clients.
</Note>

## Access and safety

Roomote MCP works with the permissions of your signed-in Roomote user. It can
use the task and context tools described above, but it does not provide general
Roomote API access or administrator privileges. Existing Roomote permissions
and connected-service access checks still apply to every request.

You can revoke the connection from your MCP client. If a saved session expires
or is revoked, Roomote asks you to approve access again in the browser.

## Troubleshooting

If your client does not open a browser or complete sign-in, make sure it
supports OAuth for remote MCP servers and that you entered the exact Roomote
MCP URL. On a self-hosted deployment, confirm that the URL is reachable from
the browser and uses HTTPS.