How to Integrate MCP with Roo Code in VS Code

Direct answer: Open Roo Code in VS Code, open its MCP settings, then choose Edit Global MCP for a user-wide server or Edit Project MCP for the current repository. Add the server under mcpServers, save the file, turn on Enable MCP Servers, and start or restart the server. Local servers use a command and arguments over STDIO; remote servers use Streamable HTTP with a URL. Roo Code stores global configuration in mcp_settings.json and project configuration in .roo/mcp.json. If both define the same server name, the project definition wins.

An MCP (Model Context Protocol) server acts as a bridge that gives Roo Code access to tools and external services such as databases, APIs, and custom scripts. Roo Code is the client, the MCP server provides tools and resources, and VS Code hosts the editor integration. See the Roo Code documentation for the current MCP settings interface.

1. Choose the configuration scope

Scope	File	Use it when	Precedence
Global	`mcp_settings.json`	You want the server in every workspace	Lower
Project	`.roo/mcp.json`	The repository needs a repeatable, project-specific setup	Higher

Open the Roo Code pane, open the MCP settings view, and select the matching edit command. Keep project files free of credentials when they are committed to source control. Put secrets in environment variables or supported secret/input mechanisms instead.

2. Add a local STDIO server

A local server is launched by Roo Code as a child process. The command starts the executable and args supplies its arguments. The optional env, alwaysAllow, and disabled fields control environment variables, tool approval, and whether the server is enabled.

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1"],
      "disabled": false
    }
  }
}

Use an absolute path while diagnosing launch problems. Once the server works, a workspace-relative path can be convenient if your server is part of the repository. Make sure the executable is visible to the VS Code extension process, which may have a different PATH from your terminal.

Windows command example

Some Windows setups need npx invoked through cmd.exe. Use the command form documented for your Roo Code version if a direct npx entry fails:

{
  "mcpServers": {
    "context7": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3. Add a remote Streamable HTTP server

For a hosted server, use type: "streamable-http" and provide the MCP endpoint. Put bearer tokens or other credentials in headers; do not commit live tokens to a public repository.

{
  "mcpServers": {
    "remote-server": {
      "type": "streamable-http",
      "url": "https://your-server.example/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      },
      "alwaysAllow": [],
      "disabledTools": [],
      "timeout": 60,
      "disabled": false
    }
  }
}

Roo Code supports per-server timeouts from 1 to 3,600 seconds; the default is 60 seconds. Increase the value only for operations that genuinely need more time. A longer timeout does not fix an unreachable endpoint or invalid authentication.

4. Enable MCP and approve tools

In Roo Code MCP settings, turn on Enable MCP Servers.
Save the configuration and use the server’s start or restart control if it is shown.
Confirm the server appears as connected.
Invoke one tool from Roo Code.
Choose per-tool approval behavior. The global Use MCP servers approval option must be enabled before an Always allow selection can take effect.

Connectivity and permission are separate. A server can be online while every tool call still waits for approval, or a tool can be auto-approved while the server itself is stopped.

5. Install a practical first server: Context7

Roo Code’s recommended-server guide uses Context7 as a general-purpose example. Add it globally or to .roo/mcp.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Save the file, enable MCP servers, confirm Context7 appears, start it if necessary, and approve its first tool invocation. Pin a package version in production if you need repeatable builds; using @latest follows the package’s newest release.

6. Add GitHub MCP Server credentials safely

GitHub’s installation flow for Roo Code is: open Roo Code MCP settings, choose Edit Global MCP or Edit Project MCP, paste the supplied configuration, replace YOUR_GITHUB_PAT with a GitHub personal access token, and save. Prefer an environment variable or a supported secret input when your configuration will be committed.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Grant the token only the permissions required for the tools you intend to use. Review every tool before selecting Always allow.

7. Roo Code files versus VS Code’s native MCP files

These formats are separate configuration systems unless your installed extension explicitly documents interoperability:

System	Project file	Top-level key
Roo Code	`.roo/mcp.json`	`mcpServers`
VS Code native workspace format	`.vscode/mcp.json`	`servers`
Portable VS Code format	`.mcp.json`	`mcpServers`

Copying a VS Code native file into Roo Code can make the server appear to be missing because the schema and discovery path differ.

8. Use ScreenshotNeo from Roo Code

ScreenshotNeo provides a website screenshot API and MCP server. Its MCP tools include take_screenshot, get_page_info, and capture_pdf, so an AI agent in Roo Code can request screenshots or PDFs through the same MCP workflow.

For a remote MCP configuration, use the MCP endpoint and authentication details shown in the ScreenshotNeo documentation:

{
  "mcpServers": {
    "screenshotneo": {
      "type": "streamable-http",
      "url": "https://api.screenshotneo.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "disabled": false
    }
  }
}

After saving, enable MCP servers, start or restart ScreenshotNeo, and approve the screenshot tool the first time Roo Code invokes it. ScreenshotNeo can also be called directly when you need a deterministic HTTP request.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', image);

Or skip the browser setup

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and whether the request was billed. Its MCP server lets AI agents take screenshots. You get 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. Troubleshooting

Symptom	Likely cause	Fix
Server does not appear	Wrong file scope, invalid JSON, or MCP disabled	Use Roo Code’s edit command, validate JSON, and turn on Enable MCP Servers.
Server appears but is stopped	Launch command, path, or permissions are invalid	Run the exact command in a terminal, use an absolute path, verify executable permissions, then restart from Roo Code.
`npx` fails on Windows	The extension cannot launch the shim directly	Invoke it through `cmd.exe /c` as shown above.
Remote server times out	Wrong URL, blocked network, slow operation, or too-short timeout	Check the endpoint independently, verify firewall and proxy access, confirm authentication, then set a suitable timeout up to 3,600 seconds.
401 or 403 response	Missing, expired, or insufficient token	Regenerate or scope the token correctly and place it in the configured environment variable or header.
Tools never run automatically	Approval policy is waiting	Enable Use MCP servers, then approve the specific tool or select Always allow.
Project change has no effect	A duplicate global server name or malformed project file	Remember that a valid project definition wins only when the names match; inspect the project JSON and restart the server.
Tools are missing	The server is online but tools are disabled	Check `disabledTools`, server logs, and the server’s advertised tool list.

10. Security checklist

Review the publisher, repository, command, arguments, environment variables, and requested tools before starting a local server.
Local MCP servers can run arbitrary code on your machine.
Keep API keys and personal access tokens out of committed JSON.
Use the narrowest token permissions that satisfy the task.
Require approval for tools that write files, modify repositories, send requests, or access private data.
Prefer a remote HTTPS endpoint when you need centralized updates and access control.

11. Performance, reliability, and cost considerations

Startup: Local STDIO servers pay process startup cost on launch or restart. Keep the process alive while working and avoid unnecessary restarts.
Latency: Remote Streamable HTTP adds network round trips. Set the timeout around the slowest legitimate operation, not an arbitrarily large value.
Scope: Global configuration reduces duplication; project configuration makes a repository reproducible and overrides a same-named global server.
Reliability: Pin package versions for repeatable local behavior, monitor server status, and keep a manual restart path.
ScreenshotNeo billing: Only clean shots are billed. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and headers report the verdict and billing result. Caching with a chosen TTL can reduce repeated captures.

12. FAQ

Can I define the same MCP server globally and per project?

Yes. When the names match, the project definition takes precedence for that workspace.

Does Roo Code read `.vscode/mcp.json`?

Roo Code’s documented project file is .roo/mcp.json. VS Code’s native file uses a different schema, so treat them as separate unless your extension version documents interoperability.

Why is a connected server still asking for approval?

Server connectivity and tool permissions are independent. Enable the global MCP approval option and approve tools individually or with Always allow.

Should I use local or remote MCP?

Use local STDIO for scripts and services that must stay on the developer machine. Use Streamable HTTP for a hosted service shared across workspaces or teams.

Can Roo Code use ScreenshotNeo without MCP?

Yes. Call the ScreenshotNeo HTTP endpoint from cURL, Python, or Node.js, or configure its MCP server so Roo Code can invoke screenshot and PDF tools directly.