<< Click to Display Table of Contents >>
The global configuration file mcp_settings.json contains a JSON object with the key "mcpServers".
Inside it, individual MCP servers are defined by name (the name is freely selectable, e.g., "SPR-Server", "filesystem", "myServer", etc.). Each server entry is a JSON object with specific fields. Which fields are allowed or required depends on the type of MCP server:
Sample for the SPR:
a) STDIO transport
Use this for a local, child-process server, (compiled EXE - no networking):
{
"mcpServers": {
"SPR-Server": {
"command": "C:\\Path\\To\\SPR_MCP_Server.exe", // your MCP server executable
"args": [], // any CLI flags here
"cwd": "C:\\Path\\To\\Working\\Directory", // optional
"alwaysAllow": [
"spr_server_assistant",
"task_execute",
"task_run",
"task_check_result",
"memory_store",
"memory_recall",
"memory_delete",
"clipboard_read",
"clipboard_write",
"apply_diff_edit",
"resources/list",
"resources/get",
"prompts/list"
],
"disabled": false
}
}
}
b) Streamable HTTP transport
Use this to talk over HTTP to a running MCP server (e.g. at 127.0.0.1:5555):
{
"mcpServers": {
"SPR-Server": {
"type": "streamable-http",
"url": "http://127.0.0.1:5555/mcp",
"alwaysAllow": [
"spr_server_assistant",
"task_execute",
"task_run",
"task_check_result",
"memory_store",
"memory_recall",
"memory_delete",
"clipboard_read",
"clipboard_write",
"apply_diff_edit",
"resources/list",
"resources/get",
"prompts/list"
],
"disabled": false
}
}
}
' Sample SPR-Script for Roo-Code:
' uses "streamable-HTTP
'SPR Script-file: MCP_Server
'Purpose:
'Author: theog
'Creation date: 07-24-2025 at 10:24:18
'===========================================================
'#EXE:?path\
'#SPI:ForceWrite
HTP.SetLogLevel|3
VAR.$$CFG=?path\mcp_config.json
VAR.$$POR=5555
VAR.$$ADD=127.0.0.1
PRT.Generating 100-line test script...
VAR.$$AIS=
FOR.$$IXX|1|4
VAR.$$AIS+PRT.This is line $$IXX->Line $$IXX$crlf$
NEX.
VAR.$$AIS+DMP.Speed$crlf$
VAR.$$AIS+MBX.!$crlf$
VAR.$$AIS+ENR.$crlf$
' --- Step 1: Initialize the Server ---
' This loads the config file (or creates it) and sets the port, etc.
MCP.Init|$$CFG
' --- Step 2: Start the Server in LISTENER mode ---
VAR.$$MSG=Server Start (Listener Mode)
' Start in Listener Mode (1)
MCP.Start|$$RES
DBP.Server started as TID: $$RES
JIZ.$$RES|Fail
MCP.IsRunning|$$RES
JIZ.$$RES|Fail
HTP.MCPShowWindow|1
' --- Step 3: Poll the Listener Queue ---
:Loop
PAU.500|ms
MCP.IsRunning|$$RES
JIZ.$$RES|Fail
HTP.MCP Simulate|RUNSCR|$$AIS
' Check the queue count
HTP.MCPGetQueueCount|$$RES
JIZ.$$RES|Loop
' Get the next command and its type from the queue
HTP.MCPGetNextCommand|$$RET|$$CMD
VAV.$$CMD=$$CMD
VAV.$$RET=$$RET
JNS.$$CMD|Loop
PRT.---------------------------------------
PRT.Dequeued Command: $$CMD
PRT.Ret=$$RET
PRT.CMD=$$CMD
PRT.---------------------------------------
' --- Use SCS to check the command type and prepare the script code ---
SCS.$$CMD
CAS.RUNSCR
' The payload in $$RET is the script code. Copy it to the execution variable.
VAR.$$SRC=$$RET
GTO.Execute
CAS.RUNPTH
' The payload in $$RET is a file path. Read the file's content into the execution variable.
CFF.$$RET|$$SRC
GTO.Execute
CAE.
' This is the default case for any unknown command types.
PRT.Unknown command in queue: $$CMD
GTO.Loop
ESC.
' This part should not be reached, but it acts as a safeguard.
GTO.Loop
:Execute
' --- Launch the script from the common variable and get its PID ---
HTP.RunScript|$$SRC|$$PID|0
JIZ.$$PID|ExecError
PRT.Launched script with PID: $$PID
' --- Wait for the script to finish, with a 5-minute timeout ---
HTP.WaitScript|$$PID|300000|$$STA
IVV.$$STA=1
PRT.Error: Script with PID $$PID timed out and was terminated.
ELS.
PRT.Script with PID $$PID finished successfully.
' (Future logic to retrieve the script's result file would go here)
EIF.
GTO.Loop
:ExecError
PRT.Error: Failed to launch script.
GTO.Loop
'===========================================================
:Fail
DBP.Server is not running.
ENR.
More Infos:
Local servers (STDIO transport) – These servers run as a local process.
The "command" field is required (string, e.g., "node", "python", "npx", or a path to the executable).
Optional fields: "args" (array of strings, arguments for the command), "cwd" (string, working directory for the process), "env" (object with environment variables). In addition, for all server types the fields "alwaysAllow" (array of tool names to auto-allow) and "disabled" (boolean, to disable the server) are optionally possible. Example for a local server entry:
"local-server": {
"command": "node",
"args": ["server.js"],
"cwd": "/project/path",
"env": { "API_KEY": "my_api_key" },
"alwaysAllow": ["tool1", "tool2"],
"disabled": false
}
In the example above, "command" and optionally "args" are the most important fields. If "url" and "type" are missing, Roo Code automatically recognizes that this is a local STDIO server.
Remote servers (Streamable HTTP transport) – For external MCP servers over HTTP/HTTPS you must explicitly set "type" to "streamable-http". You also need "url" as the full endpoint URL of the MCP server (e.g., "https://my-server.com/mcp" or for local testing "http://127.0.0.1:5555/mcp"). Optional: "headers" (object with HTTP headers, e.g., for auth tokens). Again, "alwaysAllow" (list of tools to auto-approve) and "disabled" (true/false to disable) are allowed. Important: "type": "streamable-http" is the correct value for new remote servers (not deprecated). Example for a remote server:
"my-remote-server": {
"type": "streamable-http",
"url": "https://my-server.com/api/mcp-endpoint",
"headers": {
"X-API-Key": "my_secret_api_key"
},
"alwaysAllow": ["toolA", "toolB"],
"disabled": false
}
This layout matches the recommended schema for remote MCP servers. Roo Code uses a single HTTP endpoint for all requests here and can optionally use Server-Sent Events (SSE) to stream responses.
Remote servers (Legacy SSE transport) – Older MCP servers may use the SSE protocol. Here "type" should be set to "sse" (optional but recommended if a URL is provided). Required is a "url" base path (e.g., "https://my-legacy-server.com/mcp-base"). From that, server and client usually expect fixed subpaths (e.g., /events for the event stream and /message for POST calls). Optional: "headers" as well as "alwaysAllow" and "disabled" just like above. If "type": "sse" is omitted, Roo Code tries to infer SSE based on URL conventions, but explicitly setting it is recommended. Note: SSE is considered legacy; for new servers, the Streamable HTTP type is preferred.
Server names: The keys under "mcpServers" (e.g., "SPR-Server", "memory", "context7") serve as identifiers and can be chosen freely. Just make sure each name is unique and in quotes (JSON requires string keys). Hyphens or uppercase letters in the name are allowed because they’re string keys—Roo Code examples often use short lowercase names with hyphens (e.g., "modern-remote-server"). However, these names must not be reserved keywords of the JSON structure (avoid, for example, a key named "mcpServers" inside a server). In practice, use descriptive names without spaces.
Common mistakes
When defining mcp_settings.json, errors often occur that lead to an “Invalid MCP settings JSON format” message.
Here is a list of frequent issues:
JSON syntax errors:
1. A missing or extra comma is a typical cause. Make sure to put a comma after every server entry except the last one. Example:
"server1": { ... }, ← comma after the first server
"server2": { ... } ← no comma after the last server
2. An extra trailing comma at the end of the list ("server2": { ... }, }) makes the JSON invalid.
3. Also make sure all braces are closed. For every { there must be a }, and similarly for [ and ] in arrays.
4. Wrong data types: Check that each value has the expected type. Frequent mistakes:
– Don’t write booleans as strings. For example, "disabled": false (no quotes around false).
– Lists must be arrays. For example, "alwaysAllow": ["tool1", "tool2"] instead of the incorrect "alwaysAllow": "tool1, tool2" (the value must be a JSON array, not a comma-separated string).
– Strings must be in double quotes. In particular, URLs and commands must be quoted. Without quotes, JSON won’t recognize the value as a string and you’ll get syntax errors.
5. Invalid or outdated field names:
Use exact field names from the documentation.
For example, the field for the transport type must be "type"—a field "transport" or "mode" would be unknown and either ignored or cause errors. Similarly,
"alwaysAllow" must be spelled exactly like that (case sensitive). Outdated names from earlier versions (if older docs showed other structures) should not be used.
The current Roo Code docs use only the fields listed above.
6. Wrong or outdated field values:
Ensure the values contain what’s expected. For "type" the currently valid values are "stdio", "streamable-http", and "sse". Values like "SPR" or similar are invalid,
as they don’t match an expected transport type. "streamable-http" is current and valid for remote servers (recommended default)—if your configuration throws an error,
it’s not because this value is deprecated, but rather due to syntax or another issue.
Also, "disabled" should only be true or false (not "yes"/"no").
Make sure paths and URL formats are correct (a URL should, for example, begin with http:// or https://).
Incomplete server definition: Each server entry must contain enough information so Roo Code can start or contact it.
A common mistake is creating an entry for a local server but forgetting the "command" field—the server then can’t be started.
Likewise for remote servers: without "url", Roo Code doesn’t know where to connect. Ensure that local servers include at least "command", and remote servers include at least "type" and "url". If a server isn’t needed, disable it via "disabled": true instead of omitting fields.
If an MCP server doesn’t show up or doesn’t work in Roo Code, always check the JSON structure first—even a small typo can prevent the file from loading.
Valid example
Below is an example of a correct mcp_settings.json with two servers, including a specific SPR server (as a Streamable-HTTP remote server) and another server for comparison:
{
"mcpServers": {
"memory": {
"command": "node",
"args": ["/path/to/my/memory-server.js"],
"alwaysAllow": ["read_graph", "write_graph"],
"disabled": false
},
"SPR-Server": {
"type": "streamable-http",
"url": "http://127.0.0.1:5555/mcp",
"headers": {
"Authorization": "Bearer <my_token>"
},
"alwaysAllow": [
"list_tools",
"run_script",
"list_spr_categories",
"find_spr_commands_by_category",
"find_spr_commands_by_keyword",
"get_spr_command_info",
"get_spr_topic_info",
"get_spr_path"
],
"disabled": false
}
}
}
In this example you can see the structure of the JSON document:
the root element contains the key "mcpServers", under which two servers are defined. The first server "memory" is local (STDIO) and therefore has a "command" and optional arguments.
The second entry "SPR-Server" is a remote server and therefore has "type": "streamable-http" and a "url". Both servers have a list of tools in "alwaysAllow" (here, for example, tools for the SPR server, which in your case represent special SPR functions) and the flag "disabled": false (i.e., enabled). The "headers" field in the SPR server shows an optional auth header example; if your MCP server doesn’t require an auth token, you can omit "headers" or leave it empty. The crucial point is that the JSON syntax is correct (commas and braces) and the fields follow the requirements above. This format matches the official schema—compare to a snippet from the Roo Code documentation for an HTTP-based MCP server:
Concept Overview
RooCode reads MCP configs from a JSON file whose root contains an "mcpServers" object. Each entry is a server name mapped to either a local STDIO server (requires "command") or a remote server using "type": "streamable-http" (recommended) or legacy "sse". :contentReference[oaicite:2]{index=2}
Below is a step-by-step process, followed by corrected examples and ASCII-art diagrams.
┌────────────────────────────────────────────────────────────┐
│ MCP Topology (Streamable HTTP) │
│ │
│ ┌───────────────┐ HTTP(S) ┌──────────────┐ │
│ │ RooCode MCP │ ───────────────────▶ │ SPR MCP │ │
│ │ Client │ ◀─────────────────── │ Server │ │
│ └───────────────┘ (single /mcp URL, └──────────────┘ │
│ optional SSE stream) │
└─────────────────────────────────────────────────────────────┘
┌───────────────────────────────┐
│ MCP Server Running Locally │
│ Host: localhost │
│ Port: 5555 │
└───────────────────────────────┘
↓
┌───────────────────────────────┐
│ RooCode MCP Client │
│ Global Config: mcp_settings.json │
{"mcpServers": {"SPR-Server": {"type": "streamable-http", "url": "http://127.0.0.1:5555/mcp"}}}
└───────────────────────────────┘
↓
┌───────────────────────────────┐
│ Connection Established │
│ RooCode can invoke tools │
│ and receive responses │
└───────────────────────────────┘
Corrected Minimal Configuration
Option A — remove the incomplete local server and keep only your SPR server:
{"mcpServers": {"SPR-Server": {"type": "streamable-http","url": "http://127.0.0.1:5555/mcp","alwaysAllow": ["list_tools","run_script","list_spr_categories","find_spr_commands_by_category","find_spr_commands_by_keyword","get_spr_command_info","get_spr_topic_info","get_spr_path"],"disabled": false}}}
Option B — keep both servers and make the local one valid (add "command" etc.):
{"mcpServers": {"memory": {"command": "node","args": ["/path/to/your/memory-server.js"],"env": { },"alwaysAllow": ["delete_observations","delete_relations","read_graph","search_nodes","open_nodes"],"disabled": false},"SPR-Server": {"type": "streamable-http","url": "http://127.0.0.1:5555/mcp","alwaysAllow": ["list_tools","run_script","list_spr_categories","find_spr_commands_by_category","find_spr_commands_by_keyword","get_spr_command_info","get_spr_topic_info","get_spr_path"],"disabled": false}}}
These shapes match RooCode’s documented schema: STDIO servers need "command"; Streamable-HTTP servers need "type": "streamable-http" and "url".docs.roocode.com
General Usage
1. Ensure the MCP server is reachable at the expected host and port (e.g., localhost:5555). For Streamable HTTP, the client talks to a **single** endpoint (e.g., /mcp) and may stream via SSE. :contentReference[oaicite:4]{index=4}
2. Open RooCode’s MCP settings and edit the global mcp_settings.json (or project-level .roo/mcp.json). :contentReference[oaicite:5]{index=5}
3. Add or correct your server blocks as shown above. For local servers use STDIO ("command", optional "args", "cwd", "env"); for remote servers use "type": "streamable-http" with a full "url" and optional "headers". :contentReference[oaicite:6]{index=6}
4. Save the file and reload RooCode (or use the MCP settings panel’s reload). Verify the server appears and tools are listed. :contentReference[oaicite:7]{index=7}
Common JSON Pitfalls (quick checklist)
• Trailing commas after the last item in an object/array. • Missing/extra braces or brackets.• Quoting booleans like "false" instead of false.• A local server without "command" (your case).• A remote server without "type": "streamable-http" or without "url".docs.roocode.com
Transport Reference
• STDIO — local child-process; requires "command". • Streamable HTTP — modern remote transport; requires "type": "streamable-http" and "url".• SSE (legacy) — only for older servers; prefer Streamable HTTP for new ones.docs.roocode.com
Troubleshooting
• If RooCode still flags the file, validate the JSON with an online validator; then re-check required fields per transport. :contentReference[oaicite:10]{index=10}
• On Windows, some versions reported issues connecting to newly added local STDIO servers—review RooCode issue threads if you suspect a client bug. :contentReference[oaicite:11]{index=11}
• For newer Streamable HTTP servers, ensure the endpoint matches your implementation and consider auth headers if required. :contentReference[oaicite:12]{index=12}
Appendix — Minimal Templates
STDIO (local) template
{"mcpServers": {"my-local-server": {"command": "node","args": ["server.js"],"cwd": "/path/to/project","env": {},"alwaysAllow": [],"disabled": false}}}
Streamable HTTP (remote) template
{"mcpServers": {"my-remote-server": {"type": "streamable-http","url": "http://127.0.0.1:5555/mcp","headers": {},"alwaysAllow": [],"disabled": false}}}
Once you apply either Option A or Option B above, RooCode will accept the file and your SPR-Server will connect as expected. :contentReference[oaicite:13]{index=13}
Note:
The name "SPR-Server" is just an example.
You can name the key whatever you like; the important thing is that the name is in quotes and unique.
Make sure not to forget quotes, commas, or braces.
If you paste the example above into your mcp_settings.json and adapt it to your needs, Roo Code should be able to read the servers without format errors.
Recommendations for troubleshooting
If problems with mcp_settings.json persist, the following steps help with debugging:
JSON validation: Use a JSON validator or the built-in check in VS Code to uncover format errors. Even a single wrong character can invalidate the entire file.
A validator usually points exactly to the error location (e.g., missing comma or brace). Fix all syntax errors until the file is recognized as valid JSON.
Compare with examples: Compare your configuration with the official examples from the documentation. Check field names and values for exact matches.
In particular: "type": "streamable-http" for new remote servers (mind case), "url": "http://address" in quotes, "command": "command" for local servers, etc. Ensure there are no disallowed fields—stick to the listed allowed fields per server type.
Step-by-step approach: If you have multiple server entries, try simplifying the file to narrow down the error. For example, keep only one server entry at first and check whether the error disappears. Then add the other entries step by step. This way you can determine which section causes the error.
Check names and values: Verify the names of your servers and tools. Avoid unusual characters or spaces in keys. A name like "SPR-Server" is fine, but "SPR Server" (with a space) could be problematic. As a test, change the name to something simpler (e.g., "spr-server") and see if that makes a difference. Also ensure that, for example, ports in URLs are correct and that the servers are actually reachable—a configuration value can be formally correct but substantively wrong (which won’t throw a JSON error but will cause connection problems at runtime).
Documentation and community: Consult the Roo Code documentation for up-to-date guidance. The MCP documentation is very detailed and provides examples for every scenario. If you’re unsure whether a certain field is required, you’ll find the answer there. It’s also worth checking forums or GitHub issues, as other users may have had similar problems (e.g., confirming that Streamable HTTP is supported in new versions or how certain tools should be named). Often such questions have already been resolved, and the fix is a small adjustment to the configuration.
After you’ve corrected your mcp_settings.json, save the file and restart Roo Code or reload the MCP settings.
In most cases the MCP servers should then be recognized without error messages.
Remember that a valid JSON structure is the foundation—once the format is correct, you can make full use of Roo Code’s versatile MCP features.
Good luck with the configuration!