MCP configs: what actually differs between Claude Code and Claude Desktop

I've got 11 MCP servers running in Claude Code right now - GitHub, web
fetch, search, a few local ones. Took way longer to wire up than it should
have. Not because the docs are bad, more because a config can look
completely right and just... not work, and it won't tell you why.

A few things I wish someone had told me up front.

Every server talks to you one of two ways. Either it's remote (HTTP) -
something like GitHub's own servers, where your config is basically just
a URL and a one-time login - or it's local (stdio), where your client
actually launches a program on your machine and talks to it over
stdin/stdout. Once that clicks, the rest of the format makes a lot more
sense.

Claude Code keeps its servers under the mcpServers key inside
~/.claude.json (on Windows that's %USERPROFILE%\.claude.json). That
file has a bunch of other stuff in it too - session cache, feature flags -
so don't replace it, just merge your entry into that one key.

Claude Desktop does basically the same thing in
claude_desktop_config.json, same mcpServers key, same shape for local
servers. Its support for remote/HTTP servers has moved around across
versions though, so if one of those doesn't show as connected, it's
probably a version thing, not your config being wrong.

Simplest possible example, a server that only needs Node installed:

"sequential-thinking": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}

Drop that in either file, restart the client, run /mcp in Claude Code,
and it should show connected. I actually ran this exact command before
posting, just to double check - no errors, nothing missing.

The thing that actually cost me time: two of my servers are Python-based
and use uvx instead of npx. Same idea, downloads and runs the package,
caches it after - except uv has to be installed and on PATH first
(pip install uv), and nothing warns you, the command just silently
doesn't exist. And mcp-server-fetch specifically needs
PYTHONIOENCODING=utf-8 in its env block on Windows or it throws a
UnicodeEncodeError the first time it hits a page with a curly quote or
emoji in it - so, most pages. Set that up front and you never see the
crash.

Also worth knowing: this isn't only a Claude thing. VS Code does its own
version of this in .vscode/mcp.json (a servers key), and Codex uses
.codex/config.toml with mcp_servers - TOML instead of JSON. There's a
whole discussion thread from the MCP maintainers
themselves
comparing these. I haven't actually run MCP through VS Code or Codex
myself so I won't pretend to have it solved there, just flagging it's a
real, documented mess if you're juggling more than one client.

Ended up packaging the Claude Code + Desktop side of this - both config
files, the four servers I run daily, plus the gotchas above - so nobody
else has to lose the afternoon I did. It's $12
here, or $29 if you want the troubleshooting
playbook bundled in too, here.