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.

​
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 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.

​
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.

​
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. 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. 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. 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.