Add a Remote MCP Server to Roo Code (mcp.json)

Roo Code takes a remote MCP server as one entry with a type and a url [1]:

{
  "mcpServers": {
    "my-server": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

To open the file, click the MCP icon in the top navigation of the Roo Code pane, scroll to the bottom of the MCP settings view, and click Edit Global MCP (every project) or Edit Project MCP (this project, saved as .roo/mcp.json). Roo Code creates the file if it does not exist yet [1].

Roo Code is no longer developed: its GitHub repository is archived, last updated on 15 May 2026 [3]. An installed copy still reads the settings below, but nothing will change on its side, so a newer MCP feature will not arrive. Cline, the project Roo Code was forked from, is still maintained and is set up almost the same way.

Everything below is checked against Roo Code's MCP documentation on 26 October 2026 [1].

TL;DR:

• type is required for a URL. Use "streamable-http", or "sse" for a legacy server. A URL-based entry without type causes an immediate error [1].
• The project file wins. When a server name is in both files, .roo/mcp.json takes precedence over the global mcp_settings.json [1].
• Tool calls time out after 60 seconds by default; each server can be set from 1 to 3,600 seconds [1].
• Enable MCP Servers must stay on. It is on by default, and switching it off removes all MCP from Roo's system prompt [1].

Which file, and which wins

If a server name exists in both, the project-level entry is used [1].

Add the server

The entry at the top is the whole configuration for an open server. Both fields are required for Streamable HTTP [1]:

• type: "streamable-http".
• url: the full URL of the server's single MCP endpoint, usually ending in /mcp, not the product's homepage or its docs page.

For an older server that still uses the legacy SSE transport, set "type": "sse" and give the base URL the server documents [1]. Is SSE deprecated in MCP? covers why new servers use Streamable HTTP instead.

Roo Code started as a fork of Cline, but the spelling differs: Cline's settings use "streamableHttp" [2], Roo Code's documentation uses "streamable-http" [1]. An entry copied from a Cline guide needs that one word changed.

Add an API key

A server that takes an API key gets a headers object, sent with every request [1]:

{
  "mcpServers": {
    "my-server": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Roo Code also documents ${env:VARIABLE_NAME} for reading a system environment variable, which must exist in your system environment [1]. Its example uses that syntax in a local server's arguments, so if you put it in a header, check the server's connection status after saving to confirm the key arrived. A project file you commit should not carry a literal key.

Roo Code's MCP documentation does not describe an OAuth sign-in flow [1]. A server that only accepts OAuth and answers a plain request with 401 is one to try in a client whose documentation covers that sign-in, such as Cline or Claude Code. MCP OAuth explains what that sign-in involves.

Choose which tools run without asking

Three optional fields on a server's entry control its tools [1]:

• alwaysAllow: tool names Roo Code approves automatically.
• disabledTools: tool names that are never available, even if the server offers them.
• disabled: true switches the whole server off without deleting its entry.

{
  "mcpServers": {
    "my-server": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "alwaysAllow": ["search"],
      "disabledTools": ["delete_record"]
    }
  }
}

The global Use MCP servers auto-approve setting takes precedence: if it is off, no MCP tool is auto-approved, whatever alwaysAllow says [1].

Set the timeout

Each server has a Network Timeout pulldown at the bottom of its config box in the MCP settings view, and the same value can go in the file as timeout, in seconds [1]. The default is 60 seconds, and it can be set from 1 to 3,600 [1]. A tool that does slow work, such as a long search or a report, may need more than the default.

When it will not connect

For what the server's own error codes mean, see MCP server errors and MCP server connection failed.

Check it from outside before you share it

Roo Code connects from your own machine, so a server on localhost or your VPN works for you and for nobody else. Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it passes there and fails in Roo Code, the problem is in your mcp.json, not the server.

The same setup in other clients is in Cline, Cursor, VS Code, Windsurf, Kiro, LM Studio, Raycast, Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.

Sources

1. Using MCP in Roo Code, Roo Code docs
2. Add a remote MCP server to Cline, MCP Hunter
3. RooCodeInc/Roo-Code on GitHub (archived)