# .mcp.json

> A file in a project that lists MCP servers the team shares.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** .mcp.json file, project MCP config

## Think of it like

It is like a shared phone list for a team. Everyone can call the same numbers.

## Definition

.mcp.json is a file in a project's root that lists MCP servers for the whole team. It is what claude mcp add writes when you use --scope project, and it is meant to be committed. Before using a server from it, Claude Code asks each person to approve it. Servers you add for yourself go in ~/.claude.json instead.

## Example

Emma adds the team's issue tracker server with --scope project. The .mcp.json goes into git, and each teammate approves it once.

## Example code

```json
{
  "mcpServers": {
    "docs": { "type": "http", "url": "https://mcp.example.com/mcp" }
  }
}
```

One server the whole team can use.

## Why it matters

It gives the whole team the same tools without each person adding them.

## Common mistake

Expecting a server in it to run with no question. Each person must say yes to it first.

## Three principles

- **Project root.** Committed.
- **Team servers.** --scope project.
- **Approve first.** Per person.

## Related terms

- [MCP Server](https://learn.benibix.com/term/ai/mcp-server)
- [claude mcp add Command](https://learn.benibix.com/term/ai/claude-mcp-add-command)
- [~/.claude.json](https://learn.benibix.com/term/ai/claude-json-file)

## Told apart from

- [.mcp.json vs ~/.claude.json](https://learn.benibix.com/compare/mcp-json-file-vs-claude-json-file): People think every MCP server lives in .mcp.json. Only the team's do. A server you add for yourself, in one project or in all of them, is saved in ~/.claude.json in your home folder. So .mcp.json goes into git and every teammate sees it, while ~/.claude.json never leaves your machine.

---

Source: https://learn.benibix.com/term/ai/mcp-json-file
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
