MCP config generator: mcp.json for Claude, Cursor, VS Code and more

What is an MCP JSON file?

An MCP JSON file is the configuration an AI application reads to find its MCP servers: for each server, a name plus either a command that starts it on your computer or a URL where it already runs. MCP stands for Model Context Protocol, an open standard for connecting AI applications to tools and data (see the MCP introduction or our MCP glossary entry).

There is no single universal file. Most clients use a top-level mcpServers object, but VS Code uses servers, Zed uses context_servers and Codex uses TOML tables named [mcp_servers.<name>]. Remote servers are spelled differently too (url, serverUrl, httpUrl), which is why a block copied from one client's instructions often fails quietly in another.

Where should I put the MCP JSON file?

Wherever your client reads it, at the scope you want: a project file is shared with everyone who opens the repository, a user file covers all your projects. These are the documented locations, checked 17 October 2026.

Two clients need an extra step. Claude Desktop adds remote servers as custom connectors and reaches them from Anthropic's cloud, so they must be reachable from the internet (Claude's connector guide). Windsurf's editor is now called Devin Desktop; open its file with the Cascade panel's Open MCP config file action to be sure you edit the right one.

Stdio or Streamable HTTP: which transport should I use?

Use stdio when the server is a program on your own machine, and Streamable HTTP when it runs elsewhere and you connect by URL. They are the two standard transports in the current MCP specification (2026-07-28): with stdio the client starts the server as a subprocess and talks over standard input and output; with Streamable HTTP each message is an HTTP POST to one endpoint, often ending in /mcp.

The older HTTP+SSE transport from the 2024-11-05 revision is deprecated, so pick it only for a server that offers nothing else. Recent Claude Code versions fall back to SSE by themselves, Cline assumes SSE when an entry has no type, and Gemini CLI reads url as SSE and httpUrl as Streamable HTTP. Stdio servers need their runtime installed (Node.js for npx, uv for uvx); remote servers need a token or an OAuth sign-in.

How do I add an MCP server in Claude Code?

Run claude mcp add in your project folder, then type /mcp inside Claude Code to see the connection and sign in to OAuth servers. Two examples, following the Claude Code documentation:

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport stdio --scope user filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/Documents

Everything after -- is the server's own command line. --scope local (the default) and user store the entry in ~/.claude.json; project writes .mcp.json for you to commit, and Claude Code asks for approval before using servers from it. In JSON, a remote entry needs "type": "http", because Claude Code reads an entry without a type as local. claude mcp add-json takes an entry written for another client.

How do I keep API keys out of MCP config files?

Put a reference in the file and the value in your environment or the client's secret store. Each client spells the reference differently, so the generator lets you write ${NAME} once and converts it:

• Claude Code: ${NAME} or ${NAME:-default} in command, args, env, url and headers.
• Cursor and Windsurf: ${env:NAME}; Cursor also loads an envFile.
• VS Code: ${input:id} with an inputs entry; VS Code asks once and stores the value securely.
• Codex: env_vars, bearer_token_env_var and env_http_headers name variables instead of holding values.
• Gemini CLI: $NAME, inside env only.
• Claude Desktop, Zed and Cline document no variable syntax, so keep those files private. In Claude Desktop, a server's desktop extension keeps sensitive settings in your operating system's secure storage.

Never commit a real token in a shared file such as .mcp.json or .vscode/mcp.json. If one was committed, revoke it: deleting the line does not remove it from the repository's history.

Worked example: one remote server in three clients

Choose Olano agents in the generator. It fills in a Streamable HTTP server named olano at https://your-olano-address/api/mcp with the header Authorization: Bearer ${OLANO_MCP_TOKEN}, and each client gets its own version:

• Claude Code: claude mcp add --transport http olano https://your-olano-address/api/mcp --header 'Authorization: Bearer ${OLANO_MCP_TOKEN}'. The single quotes stop your shell expanding the variable; Claude Code expands it when it connects.
• Cursor: "Authorization": "Bearer ${env:OLANO_MCP_TOKEN}" in .cursor/mcp.json.
• Codex: bearer_token_env_var = "OLANO_MCP_TOKEN", with no token in the file.

Set OLANO_MCP_TOKEN once and all three read it. Apps opened from a dock or start menu do not always see variables from a shell profile, so if the token arrives empty, start the client from a terminal. Then press Check the generated config.

Common mistakes, and a troubleshooting checklist

Most broken MCP configs come down to a few mistakes, and the checker flags each of them:

1. Invalid JSON: a trailing comma, a missing comma, single quotes, or single backslashes in a Windows path (JSON needs C:\\Users).
2. The wrong top-level key: mcpServers in .vscode/mcp.json, or servers in Cursor.
3. A remote entry missing the field the client expects: no type in Claude Code or Cline, or url instead of httpUrl in Gemini CLI.
4. A whole command line in command instead of the program there and each argument in args.
5. Relative paths and ~: clients start servers directly, not from your project folder or through a shell.
6. npx without -y: the install prompt waits for an answer no client gives.
7. A plaintext token in a file you share.

If the file is valid and the server still does not appear:

• Restart the client. Claude Desktop needs a full quit, not a closed window.
• Run the command yourself in a terminal: if it fails there, it fails in the client.
• Read the logs. Claude Desktop writes mcp.log and mcp-server-NAME.log to ~/Library/Logs/Claude or %APPDATA%\Claude\logs (MCP troubleshooting).
• A stdio server may write only MCP messages to standard output (stdio transport); logging belongs on standard error.
• Check the status: /mcp in Claude Code and Codex, MCP: List Servers in VS Code.

How Olano helps

Olano is a platform for persistent AI agents, and it works with MCP in both directions without anyone editing JSON. As a client, an Olano agent connects to servers from a library of 200+ ready-made MCP servers, or any custom one: add it on the agent's MCP tab or ask the agent in chat, and an OAuth server signs in with the Authorize button. Olano renews sign-ins before they expire (more in why MCP connections keep breaking).

As a server, Olano can publish chosen agents as ask_<agent> tools at https://<your Olano address>/api/mcp, the preset above. It is off by default, for the deployment and for each agent, and only an administrator can publish one. Callers need a token minted under Config → External access or an OAuth 2.1 sign-in an administrator approves, and actions that need approval wait for a person. See expose your agent as an MCP server, the best MCP servers for business agents, the Olano platform and security.