Skip to main content
Custom MCP servers let agents use services that Roomote does not ship a built-in integration for. Any member can add a remote server, the same way they add an integration key: shared with everyone under Integrations, or private under Personal Settings → Personal MCP servers. You can also ask Roomote in a session to connect a service’s MCP server. Remote servers become available to both sessions and sandbox tasks. Local stdio servers need a task sandbox because Roomote launches their process inside that workspace, and only deployment admins can add them. Most MCP servers publish a JSON snippet in their docs. The add dialog’s Import from JSON button accepts a pasted mcpServers snippet (or a bare server config) and prefills the form from it, for both remote and local servers. Snippets that launch mcp-remote are converted to remote servers on the upstream URL, which keeps credentials behind the Roomote proxy and enables per-tool management. Three kinds of servers are supported:

​
How remote servers are reached

Remote custom servers are never handed to the task sandbox directly. The sandbox agents and sessions use an authenticated Roomote proxy, and the proxy injects the real credentials per request. This means:
  • Header values and OAuth tokens never appear in sandbox-readable configuration or in the browser after saving.
  • Header auth covers servers that expect a static Authorization: Bearer <api-key> as well as custom schemes like x-api-key. Roomote’s own caller credentials are never forwarded upstream.
  • OAuth tokens refresh centrally, so long-running tasks keep working across token expiry.
  • Per-tool choices (the Manage tools dialog) are enforced at the proxy: disabled tools are hidden from agents and blocked even if called directly, and a task cannot run an Always ask tool until its session owner allows that exact call.

​
OAuth

For servers that support the MCP authorization spec, pick OAuth and use Connect after saving. Roomote discovers the authorization server, uses Dynamic Client Registration when the server supports it, and completes the flow with PKCE. For servers without Dynamic Client Registration, register an OAuth client for the callback URL shown in the dialog (https://<your-roomote>/api/mcp-oauth/callback) and enter the client ID and secret manually. If a token refresh is rejected by the server, the connection is marked as needing reconnection: agents get a clear error pointing at the Integrations page, or at Personal Settings for a private server, and the server card shows Connect again. Roomote sends the RFC 8707 resource indicator by default, as required by the current MCP authorization spec. A per-server toggle disables it for servers that reject unknown parameters.

​
Local (stdio) servers

Local servers run inside the task sandbox, launched with the command, arguments, and environment variables you configure. Two things to know:
  • The process runs with the same privileges as the agent itself; its environment values are visible inside the sandbox at runtime, exactly like environment-scoped stdio servers.
  • Environment values can reference deployment environment variables with ${VAR} syntax. References to Roomote runtime credentials are rejected at save time.
The sandbox image ships node, npx, uvx, and python, so npx -y <package> style servers work out of the box.

​
Who can use a server

When you add a remote server you choose who can use it:
  • Everyone in this deployment (the default) shares it with every member. Agents in every session and task can use its tools, acting with the account that authorized it. It appears on the Integrations page. The member who added it and deployment admins can edit, connect, or remove it; everyone else sees it read-only.
  • Only me keeps it private. Only your own sessions and tasks receive it, it appears under Personal Settings → Personal MCP servers, and nobody else, admins included, can see or manage it. Roomote checks the owner on every request, so a personal server’s credentials are never used on another member’s behalf.
The owner, or an admin for a shared server, can change this later from the server’s dialog. Roomote moves it between the two pages and keeps its connection, so you do not authorize again. A shared server goes private to the member who added it. Personal server names only need to be unique among your own servers, and each member can keep up to 10. A personal server stops working if its owner’s account is deactivated.

​
Scoping and precedence

Shared custom servers apply to every task. A personal server with the same name takes precedence for its owner, and an environment’s own mcpServers entry with the same name takes precedence in that environment, so the more specific scope wins. Names that collide with built-in integrations (for example linear or github) are reserved and rejected.

​
Private networks and self-hosting

For security, the Roomote control plane refuses to connect to private and special-use address ranges (RFC 1918, link-local, cloud metadata) when proxying to custom servers or running OAuth discovery. Self-hosted deployments that intentionally run MCP servers on an internal network can allow specific ranges with the R_CUSTOM_MCP_ALLOWED_PRIVATE_CIDRS environment variable, for example:
This is a CIDR list rather than an on/off switch so that opening one internal host does not expose adjacent services (databases, caches) to operator-configured URLs. Redirects from custom servers are never followed.

​
Operator controls

  • Any member can add a remote server and manages the ones they added. Deployment admins manage every shared server and are the only ones who can add local (stdio) servers. Personal servers are managed by their owner alone.
  • R_CUSTOM_MCP_DISABLED=true disables the feature entirely: custom MCP servers on the Integrations page and in Personal Settings, the proxy routes, and delivery to tasks. It is independent of R_CURATED_INTEGRATIONS_DISABLED, so a deployment can disable the built-in catalog while still using its own custom servers.
  • A custom server’s tool descriptions are provided by that server and are untrusted model input; review new servers the way you would review a dependency.

​
Notes

  • Changes to custom servers apply to newly started tasks. Remote credential edits (headers, reconnects) apply immediately because the proxy resolves them per request.
  • Editing a server’s URL or auth mode clears its stored OAuth tokens and requires reconnecting, so credentials can never be replayed against a different endpoint.