# Roo Code MCP Setup: Connecting Coding Agents to Cloud Workspaces

Roo Code MCP connects the Roo Code autonomous coding extension in VS Code to local tools and remote Model Context Protocol servers. Configuring remote cloud workspaces over Streamable HTTP gives agents direct access to versioned team documentation and project files without cluttering local disk storage or causing context bloat. Here is how to configure settings files, connect cloud storage, and manage workspace context.

Source: https://fast.io/resources/roo-code-mcp/
Author: [Tom Langridge](https://fast.io/authors/tom-langridge/)
Last reviewed: 2026-10-07

## Why Coding Agents Choke on Cloud Storage: The Context and Stub Trap

Pointing a coding agent at an unindexed cloud storage folder or a local sync directory causes immediate failures the moment the agent attempts to inspect large documentation sets or read virtual file placeholders. Desktop sync clients like OneDrive Files On Demand or Google Drive for Desktop stall when local filesystem tools attempt to read offline stubs, while raw cloud storage APIs flood the model context window with multi-megabyte payloads for simple factual lookups.

Engineering teams rarely store all project context directly in source code repositories. Architectural design records, compliance matrices, API contracts, third-party vendor specifications, and product requirement documents routinely live across enterprise cloud storage providers such as Google Drive, Microsoft OneDrive, Dropbox, Box, or SharePoint document libraries. When developers configure autonomous in-editor agents like Roo Code to implement complex features, the agent requires direct access to those external reference files.

Roo Code MCP is the Model Context Protocol subsystem within the Roo Code VS Code extension that enables the coding agent to connect to local and remote MCP servers for specialized tools and context retrieval. Developed as an open-source standard, the Model Context Protocol creates a structured JSON-RPC communication bridge between AI client applications and external context providers.

When developers attempt to connect Roo Code to cloud storage using conventional filesystem tools, they encounter two primary architectural bottlenecks:

1. Virtual file placeholder locks: Modern cloud sync daemons save local disk space by presenting remote directories as virtual filesystem stubs. These files appear in directory listings, but their actual binary contents reside in the cloud until an application requests them. When a local standard I/O (stdio) MCP server attempts to read a virtual file path, the operating system kernel attempts on-demand hydration. If the sync daemon is paused, throttled, or disconnected, the file system read call hangs. This locks the stdio process and freezes the agent execution loop until the operating system times out.

2. Context flooding and token exhaustion: Standard cloud storage APIs return whole file payloads. When an agent searches for a specific error schema inside an enterprise API guide, downloading an entire specification document or manual dumps irrelevant documentation into the model context window. This exhausts context limits, degrades reasoning quality, increases inference costs, and increases the risk of hallucinated implementations.

The solution is separating storage maintenance from local editor processes. By keeping files in existing cloud storage systems and indexing them inside an intelligent workspace, agents query targeted semantic fragments over remote MCP endpoints rather than mounting local filesystems or parsing raw binary documents in the editor.

## How to Configure Roo Code MCP: Global Versus Project Settings

Roo Code supports two distinct configuration scopes for registering Model Context Protocol servers: global configuration through `mcp_settings.json` and project-level configuration through `.roo/mcp.json`. Understanding how these two files interact allows developers to balance personal development utilities against shared repository tools.

### Global Configuration via mcp_settings.json

Global MCP settings apply across every workspace opened in VS Code. This configuration file is designed for personal utility tools that you use across all development tasks, such as local database inspectors, memory profilers, or workstation terminal runners.

Roo Code stores `mcp_settings.json` inside its extension global storage directory:

* macOS: `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
* Linux: `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
* Windows: `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json`

You do not need to edit these filesystem paths manually. In the VS Code activity bar, open the Roo Code panel, select the gear icon to open settings, click the MCP Servers section, and click "Edit Global MCP". Roo Code opens the global configuration file in an editor tab.

### Project-Scoped Configuration via .roo/mcp.json

Project-level settings configure MCP servers dedicated to a specific code repository. Creating `.roo/mcp.json` at the root of your project directory enables your entire software engineering team to share identical MCP tool definitions through Git version control.

When team members clone the repository, Roo Code automatically detects `.roo/mcp.json` and initializes the declared servers. If a server identifier exists in both the global and project-level configuration files, the project-scoped configuration takes precedence.

To keep sensitive credentials out of version-controlled files, Roo Code supports environment variable substitution using the `${env:VARIABLE_NAME}` syntax.

### Configuring Remote MCP Servers in Roo Code

While local servers use standard input and output streams (`stdio`), remote servers operate over Streamable HTTP. In Roo Code, remote HTTP servers require an explicit transport declaration.

Below is the exact JSON structure for configuring a remote MCP server in Roo Code:

```json
{
  "mcpServers": {
    "team-workspace": {
      "type": "streamable-http",
      "url": "https://mcp.fast.io/mcp/code",
      "headers": {
        "Authorization": "Bearer ${env:FASTIO_API_KEY}"
      },
      "alwaysAllow": ["search", "execute"]
    }
  }
}
```

Configuration parameter reference:

* `type`: Set explicitly to `"streamable-http"`. Roo Code does not infer transport type from URL strings; omitting this field causes connection errors.
* `url`: The remote HTTP endpoint. For coding agents connecting to Fastio workspaces, use `https://mcp.fast.io/mcp/code`. Setup procedures for people are available at `https://mcp.fast.io/docs`, while agents inspect tool definitions at `https://mcp.fast.io/skill.md`.
* `headers`: Custom HTTP headers passed with each request. Store your token in the `FASTIO_API_KEY` shell environment variable and reference it via `${env:FASTIO_API_KEY}`.
* `alwaysAllow`: An optional array of tool names permitted to execute without manual confirmation prompts during autonomous runs.

## Connecting Cloud Workspaces: Bridging Roo Code to Indexed Team Files

Software teams frequently ask how to connect existing document repositories to Roo Code without migrating away from established enterprise platforms. The practical deployment architecture maintains your existing storage repository while using an intelligent cloud workspace to handle indexing, semantic search, and remote MCP retrieval.

### Maintaining Existing Storage with Cloud Sync

Engineering organizations do not need to abandon Google Drive, OneDrive, Dropbox, or Box to give coding agents access to documentation. Instead, connect your storage provider to a Fastio workspace:

1. Connect Cloud Accounts: In workspace settings, select Cloud Sync to link your existing Google Drive, Dropbox, Box, or OneDrive account. SharePoint document libraries connect directly through the OneDrive integration.      2. Configure Sync Schedules: Cloud Sync runs one-way or two-way, on a schedule or on demand. It is never continuous, live, or real-time, preventing partial write states from being broadcast while documents are actively being edited.
3. Automatic Ingestion: As files enter the workspace, Intelligence Mode automatically indexes text documents, code files, spreadsheets, architectural diagrams, and PDF manuals.

### Hybrid Search Versus Raw File Ingestion

When an agent needs context to write code, querying an intelligent workspace avoids context bloat. Fastio builds a hybrid search index combining full-text lexical search with semantic vector retrieval.

When Roo Code calls the `search` action on the `https://mcp.fast.io/mcp/code` endpoint, the remote workspace parses the query, searches across all indexed documents, and returns only the precise paragraphs and code snippets relevant to the prompt. Each returned text fragment includes source document metadata and citations.

When unstructured files contain tabular data, requirements tables, or contract terms, Metadata Views extract structured schemas automatically. Users define fields in natural language, and the platform populates typed schemas across matching files without manual parsing scripts. Learn more about schema extraction at [Fastio document data extraction](/product/document-data-extraction/).

Independent benchmarks evaluate the efficiency of remote workspace connectors compared to traditional cloud storage access methods. The connector comparison is published at https://fast.io/benchmarks/ and that page is the only place its numbers live. Fastio was measured the fastest and the lowest cost of the providers tested.

### Workspace Plans and Allocation

Fastio organizes agent storage around shared, organization-owned workspaces. Creating a user account is free, while real project execution requires an organization on an active subscription. Monthly plans start with a 14-day trial that requires a credit card.

| Plan | Monthly Billing | Annual Billing | Included Seats | Storage Allowance | Workspace Limit | Monthly AI Credits |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| Starter | $9.99/mo | $99/yr | 3 seats | 250 GB | 5 workspaces | 100,000 credits |
| Business | $49.99/mo | $499/yr | 10 seats | 5 TB | 50 workspaces | 600,000 credits |
| Enterprise | $199.99/mo | $1,999/yr | 30 seats included (expandable up to 200 seats at $1/seat) | 25 TB | 200 workspaces | 3,000,000 credits |

Usage beyond plan allocations is billed directly in currency rather than consuming credits:

| Resource Dimension | Plan Allowance | Over-Quota Rate |
| :--- | :--- | :--- |
| Additional Storage | Included up to tier cap | 1.5 cents per GB monthly |
| Bandwidth | None; billed by use | 4 cents per GB |
| AI Processing Credits | Monthly credit allotment | $10 per 100,000 credits |

Review full plan features on the [Fastio pricing page](/pricing/).

## Comparing Local stdio and Remote Streamable HTTP Transports for Developer Teams

The choice of transport protocol directly impacts development workstation performance and team collaboration. The Model Context Protocol specification supports two primary transport implementations: standard input and output (stdio) for local processes, and Streamable HTTP for network-connected services.

The following table compares the operational characteristics of both transports for coding agent workflows:

| Operational Dimension | Local stdio Transport | Remote Streamable HTTP Transport |
| :--- | :--- | :--- |
| Process Execution | Runs as child process under VS Code | Executes on remote cloud infrastructure |
| Workstation Memory Impact | High (each server spawns runtime instance) | Negligible (stateless HTTP client requests) |
| Document Indexing Location | Local CPU, memory, and disk cache | Remote cloud vector index and search engines |
| Multi-Developer Sharing | Incompatible (isolated to single machine) | Native (shared access across entire engineering team) |
| Offline Virtual Stub Handling | Vulnerable to filesystem locks and hangs | Unaffected (retrieval happens server-side) |
| Transport Framing | Newline-delimited JSON-RPC over stdin/stdout | HTTP POST requests with optional SSE response streams |

### Multi-Developer Consistency and Memory Governance

When individual developers configure local stdio servers for project documentation, each workstation must independently run embedding pipelines, parse PDFs, and store vector caches. If an engineering team has ten developers, the organization runs ten redundant indexing processes. If a local server leaks memory or enters a compute-heavy parsing loop, VS Code editor responsiveness degrades.

Remote MCP connections enable multi-developer teams to share identical indexed storage tools. By pointing Roo Code instances across the team at a centralized Fastio workspace, every developer and agent queries the same verified context. Changes committed to existing cloud folders sync to the workspace and become searchable by all team members without local re-indexing.

### Managing Multi-Agent Concurrency with Advisory File Locks

When multiple developers or concurrent Roo Code sessions work in the same workspace, uncoordinated edits can create race conditions. Fastio handles concurrent access through advisory per-file leases managed directly via MCP actions:

* `lock-acquire`: Acquired through the `storage_manage` tool to signal active work on a target file.
* `lock-status`: Checked through the `storage` tool to inspect current lease ownership.
* `lock-release`: Released through the `storage_manage` tool when editing completes.

Because leases are advisory, they never prevent writes or corrupt files. If two agents save modifications simultaneously, both writes land safely, and per-file version history preserves every revision for inspection and rollback. Explore persistent team file organization at [Fastio storage for agents](/storage-for-agents/) and [Fastio workspaces](/product/workspaces/).

## How to Troubleshoot Roo Code MCP Server Connections and Authentication

Setting up Model Context Protocol connections occasionally produces transport or authentication errors. Diagnosing failures systematically ensures coding agents remain operational during automated development sprints.

The following table outlines common Roo Code MCP errors, their root causes, and verified fixes:

| Error Message or Symptom | Underlying Root Cause | Resolution Procedure |
| :--- | :--- | :--- |
| `Failed to connect to MCP server: team-workspace` | Missing or incorrect `"type": "streamable-http"` | Verify that the server configuration in `mcp_settings.json` or `.roo/mcp.json` contains `"type": "streamable-http"`. |
| `HTTP 401 Unauthorized` | Missing, expired, or unexpanded API token | Confirm `FASTIO_API_KEY` is exported in your environment and correctly referenced as `${env:FASTIO_API_KEY}`. |
| Tool call times out after prompt submission | Local stdio server hung on virtual file stub | Replace local filesystem stdio servers with remote workspace endpoints over Streamable HTTP. |
| Tools disappear from Roo Code interface | Invalid JSON syntax in configuration file | Validate JSON formatting in `mcp_settings.json` or `.roo/mcp.json` using a linter to fix syntax errors. |
| `Server returned invalid JSON-RPC response` | Protocol mismatch or legacy endpoint URL | Confirm the URL points to `https://mcp.fast.io/mcp/code` rather than deprecated SSE paths. |

### Step-by-Step Diagnostic Verification

When an MCP server fails to respond, follow this troubleshooting sequence:

1. Check the Extension Output Log: In VS Code, open the Output panel (`View > Output`) and select "Roo Code - MCP" from the dropdown menu. This channel logs JSON-RPC handshake messages, HTTP response status codes, and connection lifecycle events.
2. Verify Environment Variable Resolution: If you configure tokens via `${env:FASTIO_API_KEY}`, verify that VS Code inherited your active shell environment. Launching VS Code from an existing terminal session (`code .`) guarantees environment variable availability.
3. Test the Endpoint with Direct HTTP Calls: To verify that network firewalls allow outbound traffic to the MCP endpoint, execute a curl command in your terminal:

```bash
curl -i -X POST "https://mcp.fast.io/mcp/code" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ${FASTIO_API_KEY}" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2026-07-28", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'
```

A successful response returns HTTP 200 with server capabilities and protocol version metadata.

4. Refresh Active Tools in the Roo Code UI: Open the Roo Code MCP panel and click the reload icon adjacent to the server name. Roo Code re-negotiates the JSON-RPC initialization handshake and refreshes available tool definitions in active prompt sessions.

## Frequently asked questions

### How do I configure MCP servers in Roo Code?

Open the Roo Code pane in VS Code, click the gear icon in the top navigation, select MCP Servers, and choose either Edit Global MCP to open mcp_settings.json or Edit Project MCP to create .roo/mcp.json. Define your server entry inside the mcpServers object, specifying the transport type, endpoint URL, and required authentication headers.

### Where is mcp_settings.json located for Roo Code?

In Roo Code, mcp_settings.json is stored in the extension global storage directory. On macOS, the path is ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json. On Linux, it is ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json, and on Windows, it is %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json.

### How does Roo Code connect to remote storage tools?

Roo Code connects to remote storage using the Model Context Protocol over the Streamable HTTP transport. By declaring a remote server with type streamable-http and pointing to a remote workspace endpoint with a Bearer authentication token, as described in [Fastio storage for agents](/storage-for-agents/), Roo Code executes semantic searches and queries indexed files without downloading entire repositories locally.

### What is the difference between mcp_settings.json and .roo/mcp.json in Roo Code?

The mcp_settings.json file defines global configurations that apply to every VS Code workspace on your workstation. The .roo/mcp.json file defines project-specific configurations at the repository root. Project-level configurations take precedence over global settings if server names match and can be tracked in version control for team collaboration.

### Can Roo Code access Google Drive or OneDrive files through MCP?

Yes. Rather than pointing local filesystem MCP servers at desktop sync folders that use virtual file stubs, teams connect Google Drive, OneDrive, Dropbox, or Box to an intelligent workspace using scheduled Cloud Sync, or import a folder once. Roo Code then queries the indexed workspace through remote MCP tools, retrieving relevant excerpts with citations.

### Why should teams use Streamable HTTP instead of local stdio servers for team workspaces?

Local stdio servers launch as child processes on each developer workstation, consuming local memory and requiring separate local index maintenance for every team member. Streamable HTTP connects multiple developers and autonomous agents to a shared, centralized remote endpoint where file indexing, semantic search, and document extraction run in cloud infrastructure.

## Sources

- [Model Context Protocol Documentation: Architecture Overview](https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture.md): Remote MCP servers that use the Streamable HTTP transport typically serve multiple MCP clients simultaneously.
- [Model Context Protocol Documentation: Introduction](https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro.md): The Model Context Protocol is an open-source standard for connecting AI applications to external systems.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.