Disclosure: this article is from Socketlist, a free, independent MCP directory. It is adapted from our Windsurf MCP guide, which was checked against the official Cascade MCP docs on 2026-10-15.

Windsurf's Cascade agent speaks MCP well, but two things trip people up: the config file has moved since Windsurf became part of Devin Desktop, and remote servers use a field name other clients don't. Here's a working setup from scratch.

Step 1: open the right mcp_config.json

Don't hunt for the file by hand. In the Cascade panel, click the … (Actions) menu at the top right and choose Open MCP config file in the MCPs section. That opens the file Cascade actually reads.

For reference, current docs put it at:

If you edited the old ~/.codeium path after upgrading and nothing changed, that's why.

Step 2: add a local (stdio) server

Local servers use the same mcpServers shape as Claude Desktop and Cursor, so existing snippets carry over. Here's the GitHub reference server:

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

Cascade starts npx as a child process. If Node isn't on the PATH that Windsurf inherits (common on macOS when Node comes from a version manager), use the absolute path to npx.

Step 3: add a remote server with serverUrl

Remote HTTP servers don't need a command. Windsurf uses serverUrl (it also accepts url). Here's the free Socketlist server, which lets Cascade search an MCP directory:

{
  "mcpServers": {
    "socketlist": {
      "serverUrl": "https://socketlist.pages.dev/mcp"
    }
  }
}

If a server needs an API key, add a headers object next to serverUrl, for example "headers": {"Authorization": "Bearer ..."}. (Better: see step 4.)

Before adding a remote server, you can check that it answers at all:

$ curl -s -X POST https://socketlist.pages.dev/mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | jq -r '.result.tools[].name'
search_servers
get_server
list_categories
best_for

Those four names are what Cascade will list under the server once it connects.

Step 4: keep secrets out of the file

This is the feature most people miss. mcp_config.json supports interpolation in command, args, env, serverUrl, url and headers:

• ${env:VAR_NAME} reads an environment variable
• ${file:/path/to/file} reads the contents of a file

So the GitHub token never has to sit in the config:

{
  "mcpServers": {
    "socketlist": { "serverUrl": "https://socketlist.pages.dev/mcp" },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}" },
      "disabledTools": ["create_repository"]
    }
  }
}

Now the file is safe to share or back up. Export GITHUB_TOKEN in your shell profile and give the token the smallest scopes that work.

A quick sanity check that both servers are registered and of the right kind:

$ jq -r '.mcpServers | to_entries[] | "\(.key)\t\(.value.serverUrl // .value.command)"' mcp_config.json
socketlist	https://socketlist.pages.dev/mcp
github	npx

And if you broke the JSON while editing (trailing commas are the classic):

$ echo '{"mcpServers":{"a":{"command":"npx",}}}' > bad.json
$ python3 -m json.tool bad.json
Illegal trailing comma before end of object: line 1 column 36 (char 35)

Step 5: switch servers and single tools off

The MCPs section of the Actions menu lists each server with a toggle. That's the fastest way to switch a server off for a session without deleting its config.

For finer control, the disabledTools array in the example above hides specific tools from one server. That matters because Cascade can use at most 100 tools at a time. A couple of large servers (GitHub alone exposes dozens of tools) can get you there quickly. Disabling tools you never use keeps you under the limit. It also makes the agent's choices more predictable, since it has fewer similar tools to pick from.

Good candidates to disable are destructive or rare actions you'd rather do by hand: creating repositories, deleting branches, merging.

A note on Devin Local

All of this applies to the Cascade agent. The newer Devin Local agent keeps its MCP servers in the Devin CLI config instead, so servers added in mcp_config.json won't show up there. If a server "disappears" after you switch agents, that's the reason.

Recap

1. Open the config from Cascade → … → Open MCP config file.
2. Local servers: command + args under mcpServers.
3. Remote servers: serverUrl (or url), plus headers if needed.
4. Secrets via ${env:VAR} or ${file:/path}.
5. Toggle servers in the MCPs list, and trim tools with disabledTools to stay under 100.

The full Windsurf guide stays updated as the docs change. If you want tested configs to paste in, the free Socketlist sample pack is a plain zip, no signup.

Disclosure: this article is from Socketlist, a free, independent MCP directory. It is adapted from our database MCP servers guide. Star counts were taken from GitHub on 2026-10-15 and change daily.

Asking an AI assistant "which customers signed up last week but never activated?" and getting the answer from your actual database is one of the most useful things MCP does. It's also one of the easiest ways to drop a table by accident. This post covers which servers to look at and how to set them up so the worst case is a slow query, not lost data.

The landscape, grouped by engine

From the servers we track, here are the ones worth starting with:

Multi-database (one server, several engines)

• bytebase/dbhub: about 3.6k stars. A universal gateway if you hop between Postgres, MySQL and others.
• clidey/whodb: about 5k stars. A database explorer that also speaks MCP.
• executeautomation/mcp-database-server: about 390 stars, covering SQLite, SQL Server and Postgres.

PostgreSQL

• subnetmarco/pgmcp: about 540 stars, natural-language querying for Postgres.
• Also in the guide: call518/mcp-postgresql-ops for ops and monitoring and timescale/pg-aiguide.

MySQL

• designcomputer/mysql_mcp_server: about 1.4k stars.

MongoDB

• mongodb-js/mongodb-mcp-server: about 1.1k stars, maintained by MongoDB.

SQL Server and Azure

• Azure/data-api-builder: about 1.5k stars, from Microsoft.
• Aaronontheweb/mssql-mcp: about 160 stars.

Rule of thumb: if you only use one engine, pick a server for that engine. Use a multi-database server when switching configs is the bigger pain.

Rule 1: a read-only user, every time

The assistant can only do what the database user allows. So create a user for it that can't write. In PostgreSQL:

CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'change-me';
GRANT CONNECT ON DATABASE app TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

Check that writes really fail before you connect any assistant:

$ psql "postgresql://mcp_readonly:change-me@localhost/app" -c "DELETE FROM users;"
ERROR:  permission denied for table users

If that DELETE succeeds, stop and fix the grants. The equivalent in MySQL is GRANT SELECT ON app.* TO 'mcp_readonly'@'%';, and in MongoDB a user with only the built-in read role.

Start read-only even when you plan to allow writes later. You'll learn what the assistant actually asks for, and you can grant narrow write rights afterwards.

Rule 2: staging first

Point the server at a copy or a staging database for the first sessions. The assistant will sometimes run expensive queries (full scans, big joins) while it explores the schema, and you don't want to find that out on production at peak time. A pg_dump into a local container is enough.

Rule 3: connection strings go in env, not in prompts

Don't paste a connection string into chat ("connect to postgres://admin:..."). It ends up in conversation history. Put it in the env block of the server's config, which the client passes to the process and doesn't show to the model:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DSN": "postgresql://mcp_readonly:change-me@localhost:5432/app"
      }
    }
  }
}

(Each server has its own flag or variable name, DSN here. Check the README of the one you choose.) If the file lives in a repo, keep it out of git or use your client's environment-variable substitution so the secret stays in your shell profile.

Before you restart the client, confirm the file parses and the server is registered:

$ python3 -m json.tool ~/.cursor/mcp.json > /dev/null && echo ok
ok
$ jq -r '.mcpServers | keys[]' ~/.cursor/mcp.json
postgres

Rule 4: approve, don't auto-run

Most clients let you approve each tool call. For database tools, keep approval on, at least until you've seen what kind of SQL the assistant writes for your schema. Reading a proposed query takes five seconds. Restoring a table takes much longer.

What it looks like when it works

Once connected, a good first prompt is "list the tables and their row counts". It's harmless and confirms the connection. Then try something you'd normally write by hand: "average order value by month for 2026, as a table". The assistant reads the schema, writes the SQL, runs it as your read-only user and shows the result. Because the user can't write, a misunderstood request just fails with a permission error.

Checklist

• Dedicated database user with SELECT only
• Verified that a write fails with that user
• Staging or copy first
• Credentials in env, not in prompts or git
• Tool-call approval left on

More

The full guide has per-engine lists (PostgreSQL, MySQL, MongoDB, SQL Server), with live star counts and last-push dates. Our security checklist covers general MCP hygiene beyond databases.

For tested starter configs, grab the free Socketlist sample pack. It's a plain zip, no signup.

Disclosure: this article is from Socketlist, a free, independent MCP directory. It is adapted from our MCP config file locations guide.

The most common reason an MCP server "doesn't show up" isn't the server. It's the config file: wrong path, wrong top-level key, or a remote URL written in a field the client ignores. Every client reads JSON, but they don't all read the same JSON. Here's the map we use, plus a couple of shell checks to confirm a file is right before you restart anything.

The quick reference

Two lessons hide in that table:

1. VS Code is the odd one out. In .vscode/mcp.json the root key is servers, not mcpServers, and every entry gets a type.
2. Remote fields differ. Cursor uses url, Windsurf prefers serverUrl (it also accepts url), VS Code wants type: "http" with url, and Claude Desktop handles remote servers as connectors in the app instead of in the JSON file.

The shared mcpServers format

Claude Desktop, Cursor and Windsurf all accept the same local (stdio) entry. Here's the official Fetch reference server, launched with uvx:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

The client starts command with args as a child process and talks to it over stdin/stdout. If uvx isn't on the PATH the client sees, the server fails silently, which is why many people write the full path to the binary.

You can paste that block into any of the three clients unchanged. That's the best reason to keep one "source" snippet per server and copy it around.

VS Code: servers plus type

VS Code's workspace file looks similar but isn't the same:

{
  "servers": {
    "fetch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "socketlist": {
      "type": "http",
      "url": "https://socketlist.pages.dev/mcp"
    }
  }
}

Local servers say "type": "stdio", remote ones "type": "http" with a url. If you copy a Cursor snippet into .vscode/mcp.json and keep mcpServers, VS Code won't find anything.

Check the file before you restart the client

Restarting an editor to test JSON is slow. Ask jq instead. With the Cursor/Claude-style file saved as c.json:

$ jq -r '.mcpServers | keys[]' c.json
fetch

For the VS Code file (v.json), list each server and its transport:

$ jq -r '.servers | to_entries[] | "\(.key)\t\(.value.type)"' v.json
fetch	stdio
socketlist	http

Now the mistake from above. Run the mcpServers query against the VS Code file and you get:

$ jq -r '.mcpServers | keys[]' v.json
jq: error (at v.json:1): null (null) has no keys

That error means "this file has no mcpServers key". It's exactly what a client sees when you used the wrong root key.

Syntax errors are the other classic problem, and a trailing comma is the usual one. Python's built-in validator names the exact spot:

$ echo '{"mcpServers":{"a":{"command":"npx",}}}' > bad.json
$ python3 -m json.tool bad.json
Illegal trailing comma before end of object: line 1 column 36 (char 35)

JSON doesn't allow comments or trailing commas, even though most editors won't complain while you type.

Test a remote server without any client

For an HTTP server you can skip the client and call the endpoint directly. MCP is JSON-RPC, so tools/list shows what the server offers:

$ curl -s -X POST https://socketlist.pages.dev/mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | jq -r '.result.tools[].name'
search_servers
get_server
list_categories
best_for

If that returns tool names, the server works and any remaining problem is in your client config. If it doesn't, no amount of config editing will help.

Global vs project files

Cursor and VS Code both support a config file per project (.cursor/mcp.json, .vscode/mcp.json). Commit these when a team shares a server, but never commit tokens. Use the client's environment-variable support or an env block that reads from your shell. Global files like ~/.cursor/mcp.json suit personal servers you want in every project.

A short troubleshooting order

1. Right file? Open it from the client's own menu (Claude Desktop: Settings → Developer → Edit Config; Windsurf: Cascade → … → Open MCP config file). Then you know you're editing the file it actually reads.
2. Valid JSON? python3 -m json.tool file.json.
3. Right root key? mcpServers everywhere except VS Code's servers.
4. Right remote field? url, serverUrl, or type: "http" + url, depending on the client.
5. Does the server itself work? curl the endpoint or run the stdio command by hand in a terminal.
6. Fully restart the client. Many only read MCP config at startup.

Going further

The full guide links to step-by-step setup for Claude Desktop, Cursor, VS Code, Windsurf, Claude Code and Codex. There's also a config generator that writes the right shape for each client.

If you want ready-made, tested configs to start from, the free Socketlist sample pack is a plain zip, no signup.

The three scopes

What the CLI actually writes

Local scope (no flag):

claude mcp add --transport http n8n-tools http://localhost:5678/mcp/utility-tools

Added HTTP MCP server n8n-tools with URL: http://localhost:5678/mcp/utility-tools to local config
File modified: ~/.claude.json [project: /path/to/project]

The entry under that project in ~/.claude.json:

{"n8n-tools": {"type": "http", "url": "http://localhost:5678/mcp/utility-tools"}}

User scope, stdio server:

claude mcp add --scope user memory -- npx -y @modelcontextprotocol/server-memory

Top-level mcpServers in ~/.claude.json:

{"memory": {"type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"], "env": {}}}

Project scope:

claude mcp add --scope project time -- uvx mcp-server-time

.mcp.json:

{
  "mcpServers": {
    "time": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-server-time"
      ],
      "env": {}
    }
  }
}

Two details worth knowing: everything after -- is the server command and its arguments, so options like --scope and --env must come before the server name; and the CLI writes "type": "stdio" and an empty "env": {} even when you don't set any. A hand-written .mcp.json without those two fields is equivalent.

Which definition wins

From the docs: when the same server is defined in more than one place, Claude Code connects once, using the highest-precedence source, and uses that entire entry (fields are not merged):

1. Local
2. Project
3. User
4. Plugin-provided servers
5. claude.ai connectors

So a teammate's .mcp.json entry can be overridden for yourself by adding a local server with the same name, without editing the shared file.

Project servers need approval

Claude Code asks for approval before using servers from a project's .mcp.json. Until you approve, claude mcp list shows them as ⏸ Pending approval (run claude to approve). To undo your choices: claude mcp reset-project-choices.

Keep keys out of .mcp.json

.mcp.json supports environment variable expansion in command, args, env, url and headers:

• ${VAR}: the value of VAR
• ${VAR:-default}: VAR if set, otherwise default

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
    }
  }
}

Commit the file, and each person sets BRAVE_API_KEY in their own environment. If the variable isn't set and has no default, claude mcp list warns about it.

Checking what's connected

claude mcp list

n8n-tools: http://localhost:5678/mcp/utility-tools (HTTP) - ✔ Connected

claude mcp get <name> also shows the scope (Scope: Local config (private to you in this project)) and the exact command to remove it, for example claude mcp remove n8n-tools -s local.

Scripts that work on macOS, Linux and Windows

If you set up the same servers on several machines, a script is easier than copying JSON. A Bash version with a configurable scope:

#!/usr/bin/env bash
set -euo pipefail
SCOPE="${SCOPE:-local}"
claude mcp add --transport stdio --scope "$SCOPE" memory -- npx -y @modelcontextprotocol/server-memory
claude mcp add --transport http --scope "$SCOPE" context7 https://mcp.context7.com/mcp

The PowerShell equivalent:

param([ValidateSet('local','user','project')][string]$Scope='local')
$ErrorActionPreference='Stop'
claude mcp add --transport stdio --scope $Scope memory -- npx -y @modelcontextprotocol/server-memory
if ($LASTEXITCODE -ne 0) { throw 'claude mcp add failed' }
claude mcp add --transport http --scope $Scope context7 https://mcp.context7.com/mcp
if ($LASTEXITCODE -ne 0) { throw 'claude mcp add failed' }

We ran both with --scope project on the same machine (Bash, and PowerShell 7 on Linux) and compared the resulting .mcp.json files: identical. PowerShell needs the explicit $LASTEXITCODE check because a failing native command doesn't stop the script on its own. In PowerShell, quote arguments with single quotes if they contain spaces or special characters, for example --header 'Authorization: Bearer YOUR_TOKEN'.

Running a script twice fails on the first server that already exists. Remove it first with claude mcp remove <name> -s <scope>.

Disclosure: I run Socketlist, an open directory of MCP servers with install configs checked against official docs, and sell a paid Claude Code starter pack there. Everything in this article is free to use.

• Free sample (Essentials .mcp.json plus the Bash and PowerShell scripts for six servers that need no API keys): https://socketlist.pages.dev/free/socketlist-free-sample.zip
• Claude Code + MCP Starter Pack ($12): https://socketlist.pages.dev/shop/claude-code-mcp-starter-pack/