Where does Claude Code store the MCP server config?

Local and user-scope MCP servers are stored in ~/.claude.json (macOS and Linux) or %USERPROFILE%\.claude.json (Windows). Project-scope servers live in a .mcp.json file at the project root and are designed to be committed to version control. Claude Desktop is a different application and uses a separate file: claude_desktop_config.json in ~/Library/Application Support/Claude/ (macOS), ~/.config/Claude/ (Linux), or %APPDATA%\Claude\ (Windows).

Why does my MCP server fail with 'spawn ENOENT' on stdio transport?

The command field must reference an executable on your PATH or use an absolute path. If you wrote command: "claude" and claude is not on PATH, the spawn fails with ENOENT. Fix it by running `which claude` (or `where claude` on Windows) and using the full path. The generator on this page auto-quotes paths that contain spaces, which is the most common cause of broken stdio configs on Windows.

What is the difference between local, project, and user scope?

Local scope is the default: the server loads only inside the project where you added it and stays private to you, stored in ~/.claude.json keyed by project path. Project scope writes the server to .mcp.json at the project root for team sharing via version control. User scope is global to your account across all projects and is also stored in ~/.claude.json. When the same name is configured at multiple scopes, Claude Code uses the highest precedence: Local > Project > User > plugin-provided.

Is SSE transport still supported in Claude Code?

Yes, but it is deprecated. Claude Code documentation marks SSE as deprecated and recommends migrating to HTTP. The MCP specification refers to the new HTTP transport as streamable-http; Claude Code accepts both "http" and "streamable-http" as the type value, so configs copied from server documentation work without modification. New servers should use HTTP unless they have a specific reason to keep SSE.

How do I pass environment variables to a stdio MCP server?

Add an env object to the server entry: { "env": { "API_KEY": "...", "LOG_LEVEL": "info" } }. Keys must start with a letter or underscore and contain only letters, digits, and underscores. Claude Code also sets CLAUDE_PROJECT_DIR automatically in the server's environment so your server can resolve project-relative paths without depending on the working directory. In .mcp.json you can also expand environment variables from your shell using ${VAR} or ${VAR:-default} syntax for command, args, env, url, and headers fields.

Can I override the per-tool timeout for one MCP server?

Yes. Add a timeout field in milliseconds to that server entry, for example "timeout": 600000 for ten minutes. This overrides the MCP_TOOL_TIMEOUT environment variable for that server only. Values below 1000 are floored to one second. For HTTP and SSE servers, the first-byte fetch budget has a 60-second minimum regardless of this value; only the tool-call watchdog honors smaller values.

What is alwaysLoad and when should I use it?

alwaysLoad: true exempts a server's tools from Claude Code's default Tool Search deferral. Tools from an alwaysLoad server are loaded into context at session start instead of being discovered on demand. Use it sparingly — only for a small number of tools that Claude needs on every turn, since each upfront tool consumes context. The field requires Claude Code v2.1.121 or later and also blocks startup until the server connects, capped at the 5-second connect timeout.

After I paste the JSON into ~/.claude.json, how do I verify it works?

Restart Claude Code, then run `claude mcp list` in your terminal to see all configured servers and their status. Inside an active Claude session, type /mcp to see the connection status and tool count for each server. If a server stays in the 'pending' state, Claude Code will retry the initial HTTP/SSE connection up to three times with exponential backoff before marking it as failed. Stdio servers are not auto-reconnected — fix the command and restart.

Back to Tools

Claude Code MCP Config GeneratorBuild a valid `~/.claude.json` entry for stdio, HTTP, or SSE servers

Fill the form, get a copy-paste-ready Claude Code MCP server config in 10 seconds. Handles transport rules, env-var validation, Windows path quoting, and merging with your existing ~/.claude.json.

Updated May 26, 2026 · By Jim Liu(verified against Claude Code v2.1+ MCP documentation)

Example output

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_PAT"
      }
    }
  }
}

Generated for HTTP transport with Bearer auth — works in Claude Code v2.1+.

TL;DR

Pick a transport. stdio for local processes (npx, python, custom binaries). HTTP for remote servers like GitHub or Sentry. SSE works but is deprecated — prefer HTTP.
Fill the form. The generator validates server names against [a-zA-Z0-9_-]+, checks env-var keys, and auto-quotes Windows paths that contain spaces.
Merge or copy. Paste your existing ~/.claude.json to preview the full merged config and a line-level diff before applying.
Verify. After pasting and restarting Claude Code, run claude mcp list to confirm the server connected.

MCP config generator

Fill the form and the JSON updates instantly. No submit, no signup.

Server name *Used as the key in mcpServers. 'workspace' is reserved by Claude Code.

Transport

Command *Paths with spaces are auto-quoted (Windows-safe).Args (one per line)Environment variables (KEY=VALUE per line)Keys must start with a letter or underscore and contain only letters, digits, or underscores.Working directory (optional)

Advanced▾

Tool timeout (ms)Per-tool wall-clock limit. Values below 1000 are floored to 1s; HTTP first-byte budget is always at least 60s.alwaysLoad — skip Tool Search deferral for this server.dangerouslyAllowBrowserLoosens browser-context safety. Only enable for local prototypes or sandboxed tools.

Merge into existing config (optional)▾

Paste your current ~/.claude.json or .mcp.json

Server name is required.

stdio transport requires a command (for example "npx" or "python").

{
  "mcpServers": {
    "your-server-name": {
      "type": "stdio",
      "command": "your-command"
    }
  }
}

Next steps to apply this config

1Copy the JSON from the tab above.
2Open ~/.claude.json (or .mcp.json for project scope) and paste the entry.
3Restart Claude Code in your terminal.
4Run `claude mcp list` to verify the server connected.

Start from a preset

5 real-world configs

Click any card to load it into the form. You can edit before copying.

More presets coming soon.Have one to share? Open a PR with your config.

Config file paths by platform

Claude Code and Claude Desktop are two different applications with two different config files. The generator on this page produces a Claude Code MCP entry — paste it into the file below that matches your scope.

Application	Scope	File path
Claude Code	Local + User	~/.claude.json (macOS, Linux) · %USERPROFILE%\.claude.json (Windows)
Claude Code	Project (team-shared)	<project-root>/.mcp.json
Claude Desktop	macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop	Linux	~/.config/Claude/claude_desktop_config.json
Claude Desktop	Windows	%APPDATA%\Claude\claude_desktop_config.json

Note: Claude Code stores user-scope servers inside ~/.claude.json keyed by project path under a top-level projects object. When you paste an existing config into the generator, it detects either a flat mcpServers block or the per-project shape and merges in the right place.

How the generator builds the JSON

Every Claude Code MCP server entry is one object inside a top-level mcpServers map. The key is the server name (the same name you pass to claude mcp add), and the value is an object whose required fields depend on the transport type. The generator follows the schema documented in the official Claude Code MCP reference and matches the JSON that claude mcp add-json writes.

stdio transport

stdio servers run as local processes. The required fields are type: "stdio", command, and args (an array, even if empty). Optional fields include env for environment variables and cwd for working directory. Claude Code automatically injects CLAUDE_PROJECT_DIR into the spawned process so your server can resolve project-relative paths.

HTTP transport

HTTP is the recommended transport for remote servers. Required fields: type: "http" (or the alias "streamable-http") and url. Add a headers object for Bearer tokens or API keys, or leave headers blank and use OAuth — Claude Code triggers the OAuth flow when the server responds with 401 or 403.

SSE transport (deprecated)

Server-Sent Events transport is still parsed by Claude Code but is documented as deprecated. New servers should use HTTP. The fields are identical to HTTP except the type value: type: "sse".

Optional fields the generator can emit

timeout — Per-tool wall-clock limit in ms. Overrides MCP_TOOL_TIMEOUT for this server only.
alwaysLoad — true skips Tool Search deferral so the server’s tools load at session start. Use sparingly.
dangerouslyAllowBrowser — Loosens browser-context safety. Only enable for local prototypes or sandboxed tools.
oauth — Pre-configured OAuth credentials (clientId, callbackPort, optional authServerMetadataUrl). For servers without dynamic client registration.
headersHelper — Shell command that generates auth headers at connection time. Used for Kerberos, SSO, and short-lived tokens.

Env-var expansion in .mcp.json

Project-scope .mcp.json files support ${VAR} and ${VAR:-default} expansion in command, args, env, url, and headers. This lets teams check in one config and let each developer supply machine-specific paths or secrets via their shell environment.

Common errors and how the generator prevents them

spawn ENOENT

Cause: command is not on PATH or path contains spaces without quotes (common on Windows).

Fix: Use the full path. The generator auto-wraps spaces in double quotes.

Invalid server name

Cause: Name contains a space, dot, slash, or matches the reserved name 'workspace'.

Fix: Generator enforces [a-zA-Z0-9_-]+ live and blocks workspace.

JSON parse error in ~/.claude.json

Cause: Trailing comma after pasting, missing brace, or a stray smart-quote from a doc.

Fix: Paste into the Merge tab — generator parses first and shows the line of the error.

Duplicate server name overwrites a working server

Cause: You did not realize a server with the same name was already configured at a different scope.

Fix: Generator flags collisions in the pasted config with a warning before you copy.

Server pending forever

Cause: HTTP endpoint returns 5xx or refuses connection on first three retries with exponential backoff.

Fix: Check the URL with curl, then re-add the server. Stdio servers do not auto-reconnect — restart Claude Code after fixing the command.

env block ignored

Cause: env key contains a hyphen or starts with a digit, which is not a valid POSIX env-var name.

Fix: Generator validates KEY=VALUE format and rejects invalid keys before producing JSON.

Frequently asked questions

Where does Claude Code store the MCP server config?: Local and user-scope MCP servers live in ~/.claude.json on macOS and Linux, or %USERPROFILE%\.claude.json on Windows. Project-scope servers go in .mcp.json at the project root and are designed to be committed. Claude Desktop is a separate application with its own claude_desktop_config.json — do not confuse the two files. Claude Code's user-scope file is keyed by project path under a top-level 'projects' object; the generator on this page detects either flat or per-project shape when you paste an existing config.
Why does my MCP server fail with 'spawn ENOENT' on stdio transport?: The command field must point to an executable on your PATH or to an absolute path. Run 'which claude' (macOS/Linux) or 'where claude' (Windows) and paste the full path. Windows users hit this most often because paths like C:\Program Files\nodejs\node.exe contain spaces — the generator auto-wraps any command or arg that contains a space in double quotes so the shell parses it correctly.
What is the difference between local, project, and user scope?: Local is the default and is private to you in the current project. Project scope writes to .mcp.json at the repo root for team sharing via git. User scope is global to your account across all projects. When the same server name is configured at multiple scopes, Claude Code uses precedence Local > Project > User > plugin-provided > claude.ai connectors. Plugin servers and claude.ai connectors match by endpoint instead of name.
Is SSE transport still supported?: Yes, but Anthropic documentation marks SSE as deprecated and recommends HTTP. The MCP spec calls the new transport streamable-http; Claude Code accepts both "http" and "streamable-http" as the type value, so you can paste configs from server docs as-is. New servers should default to HTTP unless there is a specific reason to keep SSE — for example, an internal service that has not migrated yet.
How do I pass environment variables to a stdio server?: Use the env object on the server entry. Keys must start with a letter or underscore and contain only letters, digits, and underscores. Claude Code also injects CLAUDE_PROJECT_DIR into the spawned server’s environment automatically, so your server can resolve project-relative paths via process.env.CLAUDE_PROJECT_DIR (Node) or os.environ["CLAUDE_PROJECT_DIR"] (Python). In .mcp.json you can also expand shell env vars using ${VAR} or ${VAR:-default}.
Can I override the per-tool timeout for one server?: Yes. Add a timeout field in milliseconds to that server entry — for example timeout: 600000 for ten minutes. This overrides MCP_TOOL_TIMEOUT for that server only. Values below 1000 are floored to one second. HTTP and SSE first-byte fetch budgets have a 60-second minimum regardless; only the tool-call watchdog honors smaller values.
What does alwaysLoad do?: alwaysLoad: true exempts that server's tools from Tool Search deferral, so they load into context at session start. Use it only for a handful of tools Claude needs on every turn, because each upfront tool consumes context. The field requires Claude Code v2.1.121 or later, and the server connection blocks startup until it succeeds or hits the 5-second connect timeout.
After I paste the JSON, how do I verify it works?: Restart Claude Code in your terminal, then run `claude mcp list` to see all configured servers. Inside a session, type /mcp to view live connection status and the tool count for each server. Pending HTTP/SSE servers retry the initial connection up to three times with exponential backoff before marking themselves failed. Stdio servers do not auto-reconnect — fix the command and restart the session.

Related Claude Code guides on OpenAI Tools Hub

MCP vs A2A protocol — when to use each Claude Code MCP CLI integration guide Claude Code MCP persistence plugin — practical notes CLI to MCP converter — wrap any CLI as an MCP server Claude Code multi-agent tutorial Best Claude Code skills — curated catalog AI model comparison — Claude, GPT, Gemini side by side LLM API token cost calculator