mcp.json explained for Claude Code, Cursor and VS Code

mcp.json tells an MCP client which servers to connect to. As of November 2026, Claude Code reads mcpServers in the project-root .mcp.json, Cursor reads mcpServers in .cursor/mcp.json, and VS Code reads servers in .vscode/mcp.json. VS Code also supports a portable project-root .mcp.json that uses mcpServers.

The filename is only the start. Environment variable syntax changes between formats, so a valid JSON file can still leave your editor with no servers.

Where does each client read its config?

MCP (Model Context Protocol) lets an AI client connect to servers that expose tools. The config file names those servers and tells the client how to reach them. Our MCP server guide explains what an MCP server does.

The paths and keys below come from the Claude Code quickstart, Cursor's MCP docs, and Microsoft's MCP configuration reference.

According to Microsoft's reference, VS Code's .vscode/mcp.json supports stdio, HTTP and SSE servers. The portable project-root .mcp.json supports stdio and HTTP.

Each client also has configuration outside the project. Claude Code stores local and user-scoped servers in ~/.claude.json, Cursor uses ~/.cursor/mcp.json for servers available across projects, and VS Code has a user-profile configuration. For a broader comparison of the two coding tools, see Cursor vs Claude Code.

Claude Code reads the project .mcp.json at startup and asks for approval before using its servers in interactive sessions. You can check the project file into the repository to share the configuration with your team. See the Claude Code quickstart for the scope details.

An mcp.json example for each client

Each example below configures the same remote HTTP server. https://api.example.com/mcp is a placeholder: replace it with your server's MCP URL and set MY_SERVICE_TOKEN in your environment.

Choose the tab for the file you are editing. For VS Code's portable format, use the project-root file and variable syntax shown in the Claude Code tab.

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_SERVICE_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

{
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

If the file already exists, copy only the "my-server": { ... } entry into its existing mcpServers or servers object. Keep the other entries and add a comma between entries so the JSON stays valid.

The server name (my-server here) is the key inside the server object. For a remote server, url gives the client its address and headers can carry an authorization token. Claude Code also needs the HTTP type: without it, Claude Code treats the entry as a local stdio server, according to the Claude Code MCP docs.

A stdio server runs as a local process and uses command and args instead of a remote url. This complete Claude Code file goes in the project-root .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {
        "MY_SERVICE_TOKEN": "${MY_SERVICE_TOKEN}"
      }
    }
  }
}

The command and arguments follow Microsoft's Playwright MCP example. The env field shows how to pass a variable to a local server; use the variables your server requires. The Claude Code quickstart covers stdio entries.

Keep tokens out of project files

Environment variable references let you share a server entry without putting the token itself in the JSON. The syntax depends on the file, so copy the reference from the relevant tab along with the rest of the entry.

Claude Code also supports defaults in the form ${VAR:-default}. If a variable has no default and is unset, Claude Code uses the literal ${VAR} text and reports a warning in claude mcp list. Check the environment variable before replacing the server config, and see the Claude Code MCP docs for the variable syntax.

Cursor resolves ${env:NAME} in fields including url and headers. Its envFile field is for stdio servers; for remote servers, Cursor's docs recommend interpolation from the shell or system environment. Cursor's MCP reference also lists workspace and home-directory variables.

VS Code's .vscode/mcp.json supports input variables as well as environment variables. This example prompts for a token and inserts it into the authorization header:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "service-token",
      "description": "Service token",
      "password": true
    }
  ],
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:service-token}"
      }
    }
  }
}

VS Code stores the password input securely. The portable .mcp.json format does not support input variables, and Cursor does not resolve VS Code's ${input:...} references. See Microsoft's MCP configuration reference for the format differences and the Cursor discussion on input variables.

Why doesn't the server appear?

Check the file and top-level key first, then inspect the server entry. A config can be valid JSON and still use a key the client does not read.

For Claude Code, run claude mcp list to inspect servers and parse warnings. A malformed entry can be skipped while other entries load, so one working server does not mean every entry is valid. The Claude Code quickstart covers parse warnings, and Microsoft's reference covers the VS Code keys.

If the same server name is defined in more than one scope, Claude Code does not merge the entries. The whole entry comes from the higher-precedence scope. Run claude mcp list to see where the duplicate name is defined, then remove the entry you don't want with claude mcp remove <name> --scope <scope>, as described in the Claude Code MCP docs.

How do you connect Claude Code or Cursor to Requesty's MCP Gateway?

Requesty's MCP Gateway connects supported AI tools to multiple HTTP-based MCP servers through one gateway. It supports streamable HTTP and SSE servers. After registering a server, an administrator can explore its tools and select which ones to enable.

For other gateway options, see our MCP gateway comparison.

1. 1
   Register your server

   In Requesty, open Settings, then Integrations, then MCP Gateway. Register the server with its URL and authentication headers using the format in the MCP Gateway docs.

2. 2
   Select the tools

   Use Explore Server to discover the server's tools, then select the ones you want to enable.

3. 3
   Connect and test your client

   Set REQUESTY_API_KEY in your environment, then add the gateway entry for your client. The URL and authorization header come from Requesty's MCP integration guide.

   Claude CodeCursor

   This is a complete file for a new .mcp.json at the project root:

   JSON

   Copy

   {
     "mcpServers": {
       "requesty": {
         "type": "http",
         "url": "https://router.requesty.ai/v1/mcp",
         "headers": {
           "Authorization": "Bearer ${REQUESTY_API_KEY}"
         }
       }
     }
   }

   If the file already exists, copy only the "requesty": { ... } entry into your existing mcpServers object. Keep your other entries and add a comma between entries so the JSON stays valid.

   Test server discovery and an enabled tool call. In Claude Code, open /mcp to inspect the server status and tool list before calling an enabled read tool.

Once discovery and an enabled tool call work in one editor, copy the gateway entry from the other client's tab above, keeping that client's variable syntax and, for Claude Code, the "type": "http" field.