Trusted by 1000+ developers
Back to Glossary

.mcp.json

The .mcp.json file is a configuration format used by Claude Code to define and manage Model Context Protocol (MCP) servers at the Project Scope. It allows teams to bundle tool dependencies directly within a Git repository.

Overview

Unlike global configurations that apply to an entire system, .mcp.json is designed for team collaboration. By placing this file at the root of a project and checking it into version control, teams ensure that every developer or agent working on the repository has automatic access to the same set of MCP tools.

File Structure

The file is a JSON object where servers are defined under the mcpServers key. Each entry specifies how to connect to or launch a particular server.

json 
{
  "mcpServers": {
    "project-db-helper": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "--db", "postgres://localhost/mydb"],
      "env": {
        "DB_SCHEMA": "public"
      }
    },
    "api-proxy": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Key Configuration Fields

Field Description
command The executable to run (e.g., npx, python, node).
args An array of command-line arguments passed to the server.
env Environment variables injected into the server process.
type The transport type, typically stdio or http (for remote servers).
url The endpoint URL for remote HTTP/SSE servers.

Advanced Features

Environment Variable Expansion

Claude Code supports dynamic variable expansion using the ${VAR} or ${VAR:-default} syntax. This allows for machine-specific paths or sensitive API keys to be injected from the local environment rather than being hardcoded in the shared file.

Precedence and Scoping

In Claude Code, server definitions follow a specific resolution order if names collide:

  1. Local Scope: Private to the project but stored in ~/.claude.json (not shared).
  2. Project Scope: Defined in .mcp.json (shared via Git).
  3. User Scope: Global servers defined in ~/.claude.json.

Security and Approvals

For security reasons, Claude Code will explicitly prompt for user approval before running any server defined in a project's .mcp.json file, as these configurations can contain arbitrary commands checked in by other contributors.

Questions & Answers

How does .mcp.json help with team collaboration?

By checking .mcp.json into version control, teams can share identical MCP server configurations. This ensures that any developer joining the project has the necessary tools pre-configured and ready to use.

What happens if I have a server with the same name in my global config and .mcp.json?

The version in .mcp.json (Project Scope) will take precedence over the global (User Scope) configuration, allowing projects to override global tools with version-specific alternatives.

How do I add a server to .mcp.json?

You can manually edit the file or use the Claude Code CLI:

claude mcp add --scope project [server-name] -- [command] [args...]

Start Free