What is an MCP Configuration File?
An MCP configuration file (.mcp.json or mcp.json) is the JSON file an AI client such as Claude Code or Cursor reads to determine which MCP servers to launch or connect to. Each entry declares either a local command with arguments and environment variables, or a remote server URL.
WHY IT MATTERS
The format is broadly shared across clients: an mcpServers object keyed by server name. A local server entry specifies command, args, and env for a stdio process; a remote server entry specifies a url (and typically a transport type and optional headers). Locations vary by client: Claude Code reads a project-scoped .mcp.json at the repository root plus user- and local-scoped config, Cursor uses .cursor/mcp.json, VS Code uses .vscode/mcp.json, and Claude Desktop uses claude_desktop_config.json.
Checked-in project configs are deliberately shareable — add a server to .mcp.json, commit it, and every teammate's client offers it. That makes the file a genuine governance surface:
- Review — a new server entering the fleet shows up as a PR diff, which is the cheapest moment to ask what it is, who published it, and what its tools can do.
- Inventory — config sprawl across repositories, user scopes, and multiple clients is how tool sprawl and shadow MCP take hold; nobody holds the full list.
- Secrets —
envblocks invite credentials into version control; clients support environment-variable expansion precisely so raw keys need not be committed.
Clients add their own safeguards — Claude Code, for example, prompts before using project-scoped servers from a freshly cloned repo — but the config file itself grants whatever the named server exposes.
HOW POLICYLAYER USES THIS
PolicyLayer treats configuration as the fleet's entry point: pointing config entries at the PolicyLayer gateway means every declared server is registered, policy-evaluated, and audited centrally rather than wired directly to each client. The CLI scanner (npx policylayer) reads local MCP configs, discovers the declared servers, and classifies their tools against the catalogue at policylayer.com/tools.