Roo Code MCP Server Setup 2026: mcp_settings.json & .roo/mcp.json

How do you set up an MCP server in Roo Code? Click the settings icon in Roo Code's top navigation pane, open MCP configuration, and choose Edit Global MCP for a config that applies everywhere, or Edit Project MCP for one scoped to the current repo. Both open a JSON file with a top-level mcpServers key. Local servers need command; modern remote servers need type: "streamable-http" plus url. Roo Code detects the change and lists new tools automatically — no VS Code restart required for most edits.

Roo Code is a fork of Cline, and the two still share a lot of MCP surface area, but the config files are not interchangeable in every respect — Roo Code adds a project-level .roo/mcp.json that Cline's original design doesn't have in the same form, and Roo Code's per-tool disabledTools and watchPaths fields aren't part of Cline's schema. If you're migrating a config between the two, treat it as "close enough to adapt," not "drop-in compatible."

Quick reference

Prerequisites

Global versus project config: which one to use

Global (mcp_settings.json) applies across every workspace you open in VS Code, unless a project overrides it. Use this for servers you want everywhere — a general web-search tool, a personal filesystem server, anything not tied to one specific codebase.

Project (.roo/mcp.json) lives in the repo root and only applies to that workspace. Because it's a file in the repo, it can be committed to version control so teammates get the same MCP servers configured automatically when they clone the project — useful for a project-specific database server or an internal API wrapper that only makes sense inside that one repo. A server name defined in both files resolves to the project version for that workspace; the global entry isn't merged with it.

Step 1: Open the config through the UI

Click the settings icon in Roo Code's top navigation pane, then find the MCP section. Two buttons matter:

Either button just opens a JSON file for you to hand-edit; there's no separate GUI form for building the entry field by field beyond that.

Step 2: Add a local (stdio) server

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
      "env": {
        "DB_READ_ONLY": "true"
      },
      "alwaysAllow": [],
      "disabled": false,
      "timeout": 60
    }
  }
}

command is the only strictly required field. args supports ${env:VARIABLE_NAME} interpolation, so a path or token that varies per machine doesn't have to be hardcoded into a file you might commit:

{
  "mcpServers": {
    "internal-api": {
      "command": "node",
      "args": ["/opt/tools/internal-api-server.js", "--token", "${env:INTERNAL_API_TOKEN}"],
      "cwd": "/opt/tools"
    }
  }
}

Other optional local-server fields: cwd (working directory for the spawned process), watchPaths (file paths that trigger an automatic server restart when they change — handy while you're actively developing the MCP server itself), and disabledTools (an array of specific tool names to hide from Roo even though the server exposes them).

Step 3: Add a remote server

Roo Code supports two remote transports, and the field that distinguishes them is type:

Streamable HTTP (current, use this unless a server specifically requires SSE):

{
  "mcpServers": {
    "hosted-docs": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      },
      "timeout": 60
    }
  }
}

SSE (legacy, only for servers that document it as their transport):

{
  "mcpServers": {
    "legacy-server": {
      "type": "sse",
      "url": "https://example.com/sse"
    }
  }
}

Unlike some other MCP clients, Roo Code requires type to be set explicitly for remote servers rather than inferring it from the presence of url alone — set "streamable-http" or "sse" deliberately rather than omitting the field and hoping.

Step 4: Auto-approval, scoped per tool

Two layers control whether Roo Code asks before a tool runs:

1. A global "Enable MCP Servers" toggle in settings. Turning this off removes MCP entirely from what Roo can see and do — no tool list, no prompts, nothing. This is the kill switch, not the approval control.
2. Per-server, per-tool alwaysAllow arrays. Each server entry can list specific tool names that run without a confirmation prompt:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
      "alwaysAllow": ["read_query", "list_tables"]
    }
  }
}

Leave write-capable tools like write_query out of alwaysAllow until you've watched them run correctly a few times against real data. Auto-approval is scoped per tool name, not per server — adding a server to alwaysAllow as a whole isn't how the field works; you list the specific tools.

Managing servers after setup

From the same MCP panel: a restart button next to each server name restarts just that server's process without touching VS Code itself, an enable/disable toggle takes a server offline without deleting its config, and a per-server timeout dropdown (1–3600 seconds, default 60) controls how long Roo waits on a slow tool call before giving up. Delete removes the entry after a confirmation dialog.

A Roo-specific feature: MCP server creation from chat

Roo Code has a setting — "Enable MCP Server Creation" — that lets you ask Roo, in chat, to scaffold a brand-new MCP server rather than just consume existing ones. Roo writes the server code into a default directory (on macOS, typically under ~/Documents/Cline/MCP, a naming holdover from the Cline fork) and can register it in your config automatically. This is useful for a quick internal tool, but treat generated server code with the same scrutiny you'd give any other AI-written code that's about to run with your credentials — review it before you alwaysAllow anything it exposes.

Troubleshooting

A newly added server doesn't show up. Confirm you edited the file Roo Code's panel actually opened — mcp_settings.json via Edit Global MCP, or .roo/mcp.json via Edit Project MCP — rather than a similarly-named file elsewhere in VS Code's settings directories. Roo Code auto-detects changes to these specific files; a JSON syntax error in either one is a common reason nothing loads even though the file looks right at a glance.

"Server Not Responding." For a local server, confirm the process actually starts by running the exact command and args in a terminal outside Roo Code. For a remote server, confirm basic network reachability to the url — a corporate proxy or VPN split-tunnel is a common reason a server works from one machine and times out from another on the same team.

"Permission Errors" from a server that used to work. Check the credential in env or headers first — an expired token or a rotated API key looks identical to a Roo Code bug but is almost always the credential itself.

"Tool Not Available" even though the server is connected and enabled. Check disabledTools on that server's entry — a tool name listed there is hidden from Roo regardless of whether the server itself still exposes it. Also confirm the tool name you're expecting matches what the server actually registers; the human-readable name in any documentation isn't always the literal tool identifier.

Auto-approval isn't working for a tool you added to alwaysAllow. Confirm the global "Enable MCP Servers" auto-approval setting is on — the per-tool alwaysAllow list only takes effect when that global switch permits auto-approval at all. Also confirm the tool name string matches exactly; a label shown in the UI can differ from the literal name the server registers.

A project teammate doesn't see a server you configured. If you added it to mcp_settings.json (global), it's local to your machine only. Move it to .roo/mcp.json and commit that file if the whole team should get the same server when they open the project.

Slow performance on one specific server. Raise that server's timeout value in its config entry (up to 3600 seconds) rather than assuming Roo Code itself is slow — a tool that legitimately takes 90 seconds to return will look "stuck" against the 60-second default.

Frequently Asked Questions

Is Roo Code's MCP config the same as Cline's? Close but not identical. Both use a mcpServers JSON object with command/args for local servers and a URL-based shape for remote ones. Roo Code adds fields Cline's original schema doesn't document the same way — disabledTools, watchPaths, and a distinct project-level .roo/mcp.json file — so a config copied from Cline docs may need small adjustments rather than working unmodified.

What's the difference between global and project MCP config in Roo Code? Global (mcp_settings.json) applies to every workspace. Project (.roo/mcp.json) lives in a specific repo, can be committed so teammates share the same servers, and overrides a global entry with the same server name for that workspace only.

Does Roo Code support Streamable HTTP for remote servers? Yes, and it's the transport to use for a modern remote server — set "type": "streamable-http" explicitly. "type": "sse" remains available for servers that specifically document SSE as their only supported transport.

How do I stop Roo Code from asking for approval on every tool call from a server I trust? Add the specific tool names to that server's alwaysAllow array, and confirm the global "Enable MCP Servers" auto-approval setting is on — both have to be true for a given tool to skip the confirmation prompt. Scope this per read-only tool rather than blanket-approving a server that also exposes write tools.

Can I have Roo Code build me a new MCP server instead of just connecting to existing ones? Yes, via the "Enable MCP Server Creation" setting — ask in chat, and Roo scaffolds server code into a default directory and can register it in your config. Review generated server code before granting it any alwaysAllow tools, the same way you'd review any other AI-written code that runs with your credentials.

Related guides

Official docs cited