<!-- description: A project-specific configuration file used by Claude Code to define, manage, and share MCP servers within a Git repository. -->
# .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...]`