PulseMCP lists over 8,590 MCP servers. That number climbs every day. But an MCP server sitting in a GitHub repo does nothing until you wire it into a client that can actually call its tools.
That wiring step trips people up more than it should. Claude Desktop wants a JSON file in a specific folder. Claude Code has three different configuration scopes. OpenClaw accepts four different installation methods. And the transport protocol just changed: SSE is deprecated as of April 2026, replaced by Streamable HTTP.
This guide covers all three clients in one place. You will walk away knowing exactly where each config file lives, which transport type to pick, and what to check when your tools refuse to show up.
Pick your transport type first
MCP has two transport protocols that matter right now. Choosing the wrong one is the most common reason connections fail silently.
stdio is for local servers. The client launches your MCP server as a subprocess on the same machine, then pipes JSON-RPC messages through stdin and stdout. No network, no open ports. If you built your own MCP server in Python and want to run it on your laptop, stdio is what you want.
Streamable HTTP is for remote servers. The MCP server runs as an independent HTTP service, potentially on a different machine or in the cloud. Clients connect over the network using POST and GET requests, with optional SSE streaming for real-time responses. If you are connecting to a hosted MCP server with a URL, this is the transport.
SSE deprecation notice: The older HTTP+SSE transport is deprecated as of the 2025-03-26 MCP spec revision. SSE connections will stop being accepted on April 1, 2026. If your config uses
"transport": "sse", switch to"streamable-http"now.
The decision is straightforward:
- Server is a script or binary on your machine → stdio
- Server is a URL you connect to → Streamable HTTP
- Server is a Docker container → stdio (via Docker MCP Toolkit) or Streamable HTTP (via exposed port)
One detail worth knowing: environment variables are process-scoped for stdio servers. Each MCP server subprocess gets its own isolated set of env vars. An API key you pass to one server cannot be read by another. That isolation is intentional.
Connecting to Claude Desktop
Claude Desktop gives you three ways to add MCP servers. Which one you use depends on whether the server is local or remote, and how much you want to configure manually.
Method 1: Desktop extensions (fastest)
Go to Settings > Extensions and click Browse extensions. This opens a directory of Anthropic-reviewed MCP servers you can install with one click. No config files, no JSON editing. The extension format recently moved from .dxt to .mcpb (MCP Bundle), though existing .dxt files still work.
This is the right starting point if you want a well-known server like the filesystem, GitHub, or Brave Search. For anything custom or community-built, you will need Method 2.
Method 2: Manual JSON for local servers
Open Claude Desktop, go to Settings > Developer, and click Edit Config. This opens claude_desktop_config.json in your text editor. The file lives at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add a server to the mcpServers object. This example connects the official filesystem server:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
}
}
}If the server needs an API key, add an env block:
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "your-api-key-here"
}
}
}
}Save the file, then fully quit Claude Desktop and relaunch it. Closing the window is not enough. The app reads config only at startup. After relaunching, click the MCP indicator in the bottom-right corner of the chat input box to confirm your server and its tools are listed.
Method 3: Remote servers via Integrations
For remote MCP servers using Streamable HTTP, go to Settings > Integrations and add the server URL there. Do not add remote servers to claude_desktop_config.json directly. Claude Desktop will not connect to remote servers configured through the JSON file. Remote MCP is available on Pro, Max, Team, and Enterprise plans.
Connecting to Claude Code
Claude Code handles MCP configuration differently from Claude Desktop. Instead of one global config file, it uses three configuration scopes that control where and how servers are accessible.
Local scope stores configs in ~/.claude.json under your project path. Only you can see these servers, and only when working in that project. Good for personal dev servers or configs with sensitive credentials.
Project scope writes to a .mcp.json file at your project root. This is designed to be committed to Git so every teammate gets the same MCP tools automatically. Claude Code creates this file for you when you add a project-scoped server.
User scope also lives in ~/.claude.json but makes servers available across all your projects. It works like your personal global toolbox.
Add a server via the CLI:
# Add a remote server, scoped to the project
claude mcp add --transport http my-api --scope project https://my-mcp-server.com/mcp
# Add a local stdio server, scoped to your user
claude mcp add --transport stdio db-tools --scope user python /path/to/db_server.pyWhen the same server name exists at multiple scopes, local wins over project, project wins over user. This lets you override a team-wide server with a personal variant without touching the shared config.
Claude Code supports environment variable expansion in .mcp.json: use ${API_KEY} to reference a variable, or ${API_KEY:-fallback_value} to set a default. This keeps secrets out of version control while still sharing the server config with your team.
Connecting to OpenClaw
OpenClaw gives you the most options for adding MCP servers. Four methods, each suited to different situations.
Method 1: Edit openclaw.json directly
The config file lives at ~/.openclaw/openclaw.json. The format will look familiar if you have seen Claude Desktop configs, with one addition: OpenClaw requires a transport field.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/you/documents"],
"transport": "stdio"
}
}
}For a remote server, specify the transport as http and provide a URL with authorization headers:
{
"mcpServers": {
"remote-api": {
"transport": "http",
"url": "https://my-mcp-server.example.com/mcp",
"headers": {
"Authorization": "Bearer ${MCP_API_KEY}"
}
}
}
}OpenClaw detects config changes and hot-reloads most of the time. But changes that affect the Gateway (adding a brand-new server, changing transport types) may need a Gateway restart via openclaw gateway restart.
Method 2: The CLI
openclaw mcp add --transport stdio my-server python /absolute/path/to/server.pyThis writes the entry to openclaw.json for you. Same result as editing the file, less chance of a typo.
Method 3: ClawHub for pre-packaged skills
ClawHub is OpenClaw's skill marketplace. Many skills wrap MCP servers, so installing a skill often installs and configures the underlying MCP server at the same time.
# Install a skill (which may include an MCP server)
clawhub install serpapi-mcp
# List installed skills
clawhub list
# Update everything
clawhub update --allSkills install to ./skills under your workspace by default. OpenClaw picks them up on the next session.
Method 4: The mcp-hub meta-skill
The mcp-hub skill is a directory of over 1,200 MCP servers accessible from inside OpenClaw. Instead of hunting for servers externally, you ask your OpenClaw agent to find and connect them for you. Think of it as a search engine for MCP servers that lives inside your agent.
Security note: Treat third-party MCP servers as untrusted code, especially from ClawHub. Run them in Docker containers and audit the source before granting access to sensitive data. Our MCP security guide covers specific hardening steps.
Docker MCP Toolkit: skip the config files entirely
If you use Docker Desktop, the Docker MCP Toolkit removes most of the manual setup. It gives you a catalog of over 200 pre-built, containerized MCP servers you can enable with one click.
Open Docker Desktop, navigate to the MCP Toolkit panel, browse the catalog, and toggle on the servers you want. The toolkit handles credential injection, container networking, and client registration automatically. Each server container runs with a 1 CPU and 2 GB RAM cap, isolated from your host machine.
Currently, Docker MCP Toolkit supports Claude Desktop and Claude Code as clients. OpenClaw is not officially supported yet, though you can point OpenClaw at a Toolkit-managed server by using its exposed port with Streamable HTTP transport.
The main trade-off: the catalog only includes servers Docker has containerized. If you need a custom or community server that is not in the catalog, you are back to manual config. But for popular servers (filesystem, GitHub, databases, web search), it is the easiest way to get started.
Test before you troubleshoot
Before blaming a client config, verify the MCP server itself actually works. The MCP Inspector is the official tool for this.
npx @modelcontextprotocol/inspectorThis opens a browser UI at http://localhost:6274. Point it at your server (stdio command or HTTP URL), and it will show every tool the server exposes. Click a tool, fill in the auto-generated input form, hit Call, and see the raw JSON-RPC response.
If tools show up in the Inspector but not in your client, the problem is your client config. If tools do not show up in the Inspector, the problem is the server itself. This step saves you from chasing client config problems when the real issue is the server.
The Inspector also displays resources and prompts your server exposes, plus the full JSON-RPC message exchange. When you hit a malformed response or a schema mismatch, you will see it here first.
When things go wrong: 7 fixes for common connection failures
Most MCP connection failures come down to one of these seven issues. Work through them in order.
1. Invalid JSON. A missing bracket, a trailing comma, or an unescaped backslash in a Windows path will break the entire config file. Paste your config into a JSON validator before restarting. Claude Desktop will not tell you your JSON is malformed. It will just silently ignore the file.
2. Wrong config file location. On macOS, the Claude Desktop config is at ~/Library/Application Support/Claude/, not ~/Library/Claude/. On Windows, it is %APPDATA%\Claude\. If you are editing the wrong file, nothing will happen.
3. PATH not available. Claude Desktop launches MCP server subprocesses with a stripped-down shell environment. Commands like npx, node, or python may not be found even though they work in your terminal. Fix: use absolute paths to the binary. On Windows, you may need to use "command": "cmd" with "/c" as the first argument.
4. Transport mismatch. Pointing a stdio config at a server that expects HTTP connections (or vice versa) fails without a useful error message. Match the transport to the server type.
5. Server initializes but tools are absent. The server process starts, the client says it is connected, but no tools appear. This usually means the server threw an error during tool registration. Check server logs or run it through MCP Inspector to see if tool schemas are valid.
6. Authentication failures for remote servers. Token expired, wrong header format, or the environment variable holding your API key is not set. Double-check that ${VAR} references resolve to actual values in your environment.
7. You forgot to restart. Claude Desktop reads config at launch only. You must fully quit (not minimize) and reopen. OpenClaw hot-reloads most changes, but adding an entirely new server or changing its transport may need openclaw gateway restart. Claude Code picks up .mcp.json changes automatically.
What to do next
Once an MCP server is connected, your agent can actually do things: read files, hit APIs, query databases. Getting the config right and picking the correct transport is the whole job.
If you do not have a server to connect yet, our Python MCP server tutorial walks through building one from scratch. If you have an OpenClaw setup and want to lock down security before connecting third-party servers, start with the Docker sandboxing guide.
If you run into a connection issue not covered here, drop a comment and I will add it to the troubleshooting list.