Skip to main content
Roomote MCP brings your Roomote workspace into the coding tools you already use. From any OAuth-capable MCP client, you can start a session, inspect its conversation and delegated tasks, and follow up without switching back and forth between tools.

What you can do

Start a Session

Ask your MCP client to start Roomote with a clear message. The ordinary start action creates a session, where Roomote can answer directly or delegate repository work to tasks. You can keep working locally and return to the same session for the result. When work must start directly in a known compute environment, your client can still use the explicit environment-targeted task launch action. Your client can include supported screenshots, files, logs, or documents when it starts a session or sends a follow-up. A message accepts up to 20 attachments and 16 MiB of decoded attachment data in total. See File attachments for supported formats, processing behavior, and request limits.

Choose a model when starting

To choose the session’s configured model, call manage_tasks with action: "start", message, and an exact model ID from list_models. Optionally include reasoningEffort only when the listed metadata publishes that value in supportedReasoningEfforts. The native POST /api/mcp/sessions accepts the same fields with a Roomote user auth token:
The response remains { "sessionId": "...", "fastConversationId": "...", "queued": true }. Unknown, disabled or non-exact IDs, unsupported efforts, and efforts whose supported values are unknown are refused with HTTP 400; the selection is never replaced with a different choice. Effort requires an explicit model. Omit both fields to inherit defaults. These session choices do not automatically select models for delegated tasks. Session summaries expose configuredModel; task summaries and a session’s child task latestRun expose configuredModels, keyed by coding and any stored non-coding role overrides. For example:
This example illustrates the summary’s additional field. explicit means a stored choice/override, not an attribution to a particular user. default with a null value means no stored override and inheritance from configuration; it does not resolve or snapshot the inherited default. Sources are independent for model and effort. A task without a latest run has configuredModels: null. These fields describe current configuration only, not the model actually used after resolution, routing or provider fallback, and do not prove execution.

Check on and steer existing work

Search finds Sessions by default. Once you find one, provide its Session ID to read the summary or newest conversation messages and to send a follow-up. When you need one concrete coding task instead, use task search and pass its task ID; the task ID takes precedence if both identifiers are supplied. Compute logs, cancellation, environment-targeted launch, and task model controls remain task-specific operations. For extended coordination, clients can use get_updates instead of re-reading the full transcript. Each response contains only new user-visible narrative in chronological order, an opaque cursor for the next poll, current session or task state, and an explicit response-needed flag. Tool calls, tool results, hidden reasoning, and transcript metadata are excluded. Reusing the cursor after no new activity returns an empty narrative delta rather than the same messages again; full transcript reads remain available for debugging. When relaying between an MCP client and Roomote, summarize substantive messages with the labels Client → Roomote and Roomote → Client. Relay questions or input needs promptly, skip narration for unchanged polls, and make the final answer self-contained. Relay summaries should cover visible narrative and decisions, not credentials, raw tool traces, hidden reasoning, or oversized internal payloads. Successful follow-up sends include the exact target and text accepted by Roomote so the client can summarize the outbound message without guessing. For content authored by an agent and sent to Roomote, prefix the message with Agent (on behalf of user):. This is an untrusted textual convention that helps the receiving Roomote agent avoid attributing the words to the human, not verified sender provenance. It does not authorize the agent to speak as or impersonate the user. This is useful when you want to:
  • catch up on a session that is already active
  • find an earlier investigation or implementation
  • inspect a delegated task when you need its execution details
  • pull the result of a Roomote task into your current conversation
  • send follow-up instructions with supporting files or cancel task 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.

Discover available models

Use manage_tasks with action: "list_models" to discover the deployment’s enabled models available to your signed-in account. All active members share this deployment catalog. Disabled models are excluded; discovery does not contact inference providers or guarantee current provider quota or capacity. For HTTP clients, GET /mcp/models accepts the same OAuth bearer access token as /mcp (the /mcp resource and mcp:roomote scope). It also accepts Roomote’s existing user auth tokens. Run tokens are not accepted.
  • limit: integer from 1 to 100, default 50
  • query: case-insensitive substring of exact ID, display name or family; trimmed, at most 200 characters
  • cursor: opaque nextCursor from the previous response; keep the same query
This is an illustrative response. IDs are returned unchanged from the enabled catalog. metadata preserves existing model metadata, including supportsReasoning and supportedReasoningEfforts when known. Missing metadata means unknown, not unsupported; discovery does not infer thinking levels. defaultModelId is the configured task default even if it is absent from the filtered page. isDefault marks a matching entry. These are task-catalog defaults, not a promise about the model an individual session or run uses. Results are ordered by exact ID. Follow nextCursor until it is null; each page is bounded even for large catalogs. Pages reflect current settings, not a frozen snapshot: restarting enumeration is appropriate if settings change. Invalid limits, queries or cursors return HTTP 400. Responses are not cached.

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.

Read a public URL

Roomote MCP’s fetch_url tool can fetch text or supported images from a public HTTP or HTTPS URL. Text can be returned as Markdown, plain text, or raw HTML; HTML is converted when Markdown or text is requested. Requests default to a 30-second timeout, allow a caller-selected timeout up to 120 seconds, and return at most 5 MiB of decompressed content. HTML-to-Markdown conversion is limited to 1 MiB of HTML to keep parsing bounded in the application process; request plain text or raw HTML for larger pages. Callers may provide explicit request headers, including authorization headers. Roomote sends only the supplied values and never inherits deployment, user, integration, or task credentials or cookies. Explicit sensitive headers are preserved across same-origin redirects and removed before a cross-origin redirect. Transport-controlled headers such as Host and Content-Length cannot be overridden. Roomote agents use this tool instead of the client runtime’s generic fetch tool so sessions and coding tasks get the same behavior. The tool treats every response as untrusted data, rejects private, internal, reserved, and other non-public destinations, checks and pins every resolved address, revalidates every redirect, and supports only default HTTP and HTTPS ports. These are application-level SSRF protections, not network egress isolation: they do not restrict shell commands, browsers, or other networking available inside a coding sandbox.

Open an artifact

Use open_artifact when you need to inspect an artifact from an accessible task or Session. Pass the exact owning task or Session ID and stored artifact path; a task run may omit the task ID to use its bound current task. The result includes artifact metadata and bounded content for supported text formats up to 64 KiB. Binary, unsupported, or oversized artifacts should be opened through their artifact link or downloaded instead. Roomote checks access to the owning task or Session before reading content.

Read task files and command receipts

Public manage_tasks supports these reads for a task you can access, including finished tasks. Pass the task ID rather than the parent session ID:
This returns artifacts with IDs, task/run IDs, paths, versions, types, sizes and creation times. It lists the latest successfully uploaded version of each path. Add artifactType (general, plan, or visual-proof) to filter the list. Files left in a sandbox but never uploaded are not included.
The response includes artifact metadata, url, authentication: "bearer" and expiresAt: null. Omit version for the latest uploaded version, or pass an exact version. Fetch the URL with Authorization: Bearer using the same credential as your public MCP connection. The URL alone grants no access: Roomote rechecks task visibility and privacy on every download. Private tasks remain owner-only, and downloads are not cached. The URL has no separate signed-link expiry, but the credential must still be valid. A client opening links without authorization headers cannot download these files.
This returns receipts oldest first, with message/run/tool-call identifiers, session/turn identifiers where recorded, timestamps, command, nullable exitCode, status and output. Use the returned nextCursor with the same task ID to read the next page. limit defaults to 50 and accepts 1–100. Output retains up to 20,000 characters of source text, plus a truncation marker when needed. outputTruncation is null for untruncated output, or gives originalChars, keptChars and strategy: "head_tail". These are stored shell-tool results, not a complete operating-system command audit. Commands run inside scripts or background processes are not separate receipts; a missing exit code stays null. A command interrupted before a result was recorded may have no receipt. Compute logs remain available separately with get_compute_logs and are not a command history.

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 session to investigate this bug.”
  • “Find my active sessions related to OAuth and summarize their progress.”
  • “Find the coding task for this pull request and show its compute logs.”
  • “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.”
  • “Read the latest messages from this session and send a follow-up.”
  • “Use this Slack message as context and explain what the team decided.”
  • “Read this public documentation page and summarize its authentication requirements.”
  • “Cancel the task working on the old approach.”

Connect your MCP client

Use your Roomote URL with /mcp appended:
For example:

Claude Code

Add Roomote at user scope so it is available across your projects, then start the browser sign-in:
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:
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:
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.
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.

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.

Manage connected clients

Open Settings → Personal → Connected MCP clients to see and revoke your authorizations. Admins can open Settings → Users, choose an MCP authorization owner, and revoke one client or Revoke all for that user. These controls affect inbound access to Roomote, separately from outbound integrations. Each user’s authorization is independent, even when multiple users connect through the same registered client. The list includes clients awaiting their first token exchange. It shows expiry, last authenticated request, and last token exchange separately. Historical timestamps that were not recorded before an upgrade appear as Not recorded. Client names are supplied by the client, not verified publisher identities. Revocation stops subsequent authenticated requests, including already-issued access tokens; work already accepted can finish. Reconnecting requires browser consent and creates a fresh authorization. Old tokens remain invalid after reconnecting. You can also revoke from your MCP client using the OAuth revocation endpoint. Revocation preserves the reusable client registration. Access tokens last one hour. Clients that request refresh tokens can refresh access within a 30-day session; rotating a refresh token does not extend that session. The client registration is separate: each successful authorization code exchange or token refresh keeps the same client ID available for another 90 days. Token expiration or revocation does not itself delete that registration or let a revoked token regain access.

Upgrading an existing deployment

Existing connections with a live refresh session can be preserved. Roomote automatically backfills those sessions when they refresh or when their owner’s client list is opened. This preserves the original remaining expiry; it does not grant another 30 days. No database migration or Redis commands are required. Previously issued access tokens do not identify their client authorization, so they cannot be safely backfilled or selectively revoked. After the enforcing API upgrade, those tokens receive 401 Unauthorized. A refresh-capable client can use its existing refresh token to obtain a tracked access token and continue. If the client does not refresh after a 401, reconnect it once. Clients without a refresh token, expired sessions, and in-progress authorization codes from the old version must repeat browser consent. A missing or expired client registration requires removing and re-adding the connection. For a staged self-hosted rollout, deploy the updated web authorization server first, drain all old web instances, then deploy the updated API. The previous API accepts the additional token claims but does not enforce live revocation; prompt revocation is guaranteed only after every API instance is updated. Do not continue running an old authorization server after enabling enforcement: it can only issue untracked access tokens. A coordinated deployment is also supported, but clients may need to refresh once when the API changes. OAuth access requires available Redis on every authenticated request. During an outage access is refused rather than trusting a potentially revoked token; retry after Redis recovers. Losing Redis authorization data requires reconnecting. Backfill cannot recover expired or lost sessions. Reverting the API removes prompt-revocation enforcement; reverting the authorization server can require reconnecting already-migrated clients because their legacy refresh state was replaced. Keep web and API versions coordinated during rollback too. To limit unused registrations, initial registration must be followed by a successful authorization code exchange within one hour. After 90 days without a successful exchange or refresh, an activated registration expires. If that happens, remove and re-add Roomote in your MCP client to register again.

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.