MCP JSON config: what's in mcp.json and why clients differ

An MCP JSON config file tells an MCP client which servers to use. Its top-level object maps each server name to an entry: a local server gets a command with args and optional env, and a remote server gets a URL, plus headers when it needs a key. Clients agree on that shape but not on the key names. VS Code uses servers where Cursor and Claude Code use mcpServers, and Android Studio calls the URL httpUrl, so write each entry for the client that reads it.

The key names come from each client's own docs: Cursor, Claude Code, VS Code, GitHub Copilot CLI, Copilot in JetBrains IDEs, and Android Studio, plus the MCP docs' Claude Desktop example, all read on 2026-09-28. The Sume entry comes from Sume's MCP quickstart and OAuth and API keys pages. Sume's basics page says hosted MCP still works but is not the primary path today, and Sume has no official connector for any of these clients: each entry is a plain remote MCP connection.

What is an mcp.json file?

It is where a client reads its list of MCP servers. The first entry below is the MCP docs' Claude Desktop example: a filesystem server started with npx, with the folders it may use as args. The second is the remote entry Sume's quickstart gives for Cursor, which is only a URL.

// Local server: Claude Desktop's claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

// Remote server: Cursor's mcp.json, from Sume's quickstart
{
  "mcpServers": {
    "sume": { "url": "https://mcp.sume.com/mcp" }
  }
}

Why is the MCP config different in each client?

Each client defines its own file, so a copied entry can fail on a key name. For a remote server:

Can one config file work in several clients?

Partly. A .mcp.json file with a top-level mcpServers object is Claude Code's project file, one of the project files Copilot CLI loads, and what VS Code calls its portable format. Give each remote entry "type": "http": Claude Code reads an entry with no type as a stdio server, so a url alone is a configuration error there. For Sume, that entry is:

{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp"
    }
  }
}

Where do API keys go in an MCP config?

Not into a file you commit. Sume's quickstart prefers OAuth for interactive clients: an entry without headers lets the client run Sume's sign-in, and Sume's consent page leaves Write off unless you turn it on. For automation that doesn't speak OAuth, Sume accepts Authorization: Bearer $SUME_API_KEY or x-api-key. Reference the key through the client's variable syntax instead of pasting it:

• Claude Code expands ${VAR} and ${VAR:-default} in .mcp.json, including url and headers, as in "Authorization": "Bearer ${SUME_API_KEY}".
• Cursor resolves ${env:NAME} in command, args, env, url, and headers.
• VS Code prompts for an ${input:…} value when the server first starts, then stores it securely.
• Rotate a Sume key if it ever appears in logs or chat history. VS Code remote MCP server walks through the VS Code version.

Why doesn't my MCP server load from the config?

Check the client-specific rules first:

• Claude Code skips a server whose entry has a url but no type, and says so in the error.
• Copilot CLI doesn't read .vscode/mcp.json; its top-level servers key is unsupported there.
• Copilot CLI loads project-level servers only after you confirm folder trust, and skips them silently in untrusted directories. In interactive sessions, Claude Code asks for approval before it uses servers from a project's .mcp.json.
• Android Studio's httpUrl is for streamable HTTP endpoints; its docs say to use url for an SSE endpoint. Sume's quickstart asks for a streamable HTTP server, so use httpUrl there.