Configuring .mcp.json vs. ~/.claude.json: Managing Project Hierarchy in Enterprise Codebases

The Enterprise Configuration Dilemma

As engineering organizations roll out AI coding assistants like Claude Code across distributed development teams, configuration management quickly becomes a critical architectural bottleneck. In a complex enterprise environment, developers need seamless access to specialized external tools—such as internal database schemas, Jira ticket tracking, proprietary design system linters, and AWS environment inspectors—via Anthropic’s Model Context Protocol (MCP).

However, hardcoding tool definitions and environment variables into arbitrary local files creates massive technical friction. If every developer configures their MCP servers independently, onboarding slows to a crawl, tool definitions drift, and security teams face the nightmare of exposed API keys checked into version control.

To solve this, Claude Code enforces a strict configuration hierarchy. Mastering the distinction between the global user scope (~/.claude.json) and the repository project scope (.mcp.json) is foundational for engineering leads, and is heavily evaluated on the Claude Certified Architect – Foundations (CCAR-F) exam under Domain 2 (Tool Design & MCP Integration) and Domain 3 (Claude Code Configuration & Workflows).

Understanding ~/.claude.json (Global User Scope)

The ~/.claude.json file resides in the individual developer’s home directory and serves as the global user profile. Configurations defined here apply universally across every project, repository, and terminal session that the developer executes on their local machine.

What Belongs in the Global Scope?

• Developer-Specific Utility Servers: General-purpose developer productivity tools that are not tied to any single codebase, such as local filesystem explorers, general GitHub API wrappers, or personal notification integrations.

• Individual User Preferences: Custom execution flags, personal theme choices, default interactive behavior settings, and global permission auto-approvals for low-risk local tools.

• Local Authentication Tokens: Personal access tokens (PATs) or developer-specific API keys required to authenticate with external SaaS tools. Because ~/.claude.json sits outside the git repository, it is inherently isolated from shared source control.

Understanding .mcp.json (Repository / Project Scope)

The .mcp.json file (often placed in the project root or within a .claude/ subdirectory) represents the shared repository scope. This file defines the exact Model Context Protocol servers required to develop, debug, and test that specific codebase.

What Belongs in the Project Scope?

• Project-Specific Data Sources: MCP servers that connect directly to the application’s local development database, microservice endpoints, or project-specific GraphQL schemas.

• Custom Internal Tooling: Proprietary MCP servers engineered by your internal DevOps or architecture teams—such as a custom deployment linter, an internal security vulnerability scanner, or a project documentation indexer.

• Standardized Team Environments: Explicit command paths, container runtime arguments (docker run ...), and required environment variable keys needed to spin up the tool stack reproducibly across the entire engineering team.

Because .mcp.json contains no personal secrets, it should always be checked into version control (Git). This guarantees that when a new engineer clones the repository and launches Claude Code, the entire suite of project-specific AI tooling initializes automatically with zero manual setup.

Configuration Hierarchy and Merge Rules

When Claude Code initializes in a terminal directory, it evaluates and merges configuration layers dynamically at runtime. Understanding how these scopes interact is essential for debugging tool misrouting and preventing workspace collisions.

[ Global Scope: ~/.claude.json ]  --->  (Base productivity tools & personal keys)
                                                  │
                                                  ▼
[ Project Scope: ./mcp.json ]     --->  (Repo-specific MCP servers & team tools)
                                                  │
                                                  ▼
[ Runtime Execution ]             --->  (Merged tool array exposed to Claude)

1. Scope Precedence and Overrides

If a Model Context Protocol server is defined with the exact same identifier in both the global ~/.claude.json and the local .mcp.json, the project scope takes precedence. The repository-level configuration overrides the global user setting for that specific workspace. This allows a team lead to override a developer's default global database tool with a strictly scoped, project-specific local sandbox instance.

2. Array Merging

For distinct, non-overlapping tools, Claude Code merges the arrays cleanly. If a developer has a global Git MCP server in ~/.claude.json and the team repo defines a custom SQL MCP server in .mcp.json, Claude has runtime access to both servers simultaneously during an active coding session.

Strategic Scope Comparison

Security and Governance Guardrails

In enterprise architectures, mixing configuration hierarchy with improper secret management can trigger catastrophic security incidents. When designing project-level .mcp.json files for your team, enforce two mandatory architectural guardrails:

1. Never Commit Secrets to .mcp.json

Because .mcp.json is committed to shared source control, hardcoding API keys, database passwords, or enterprise authentication tokens directly into the file is a severe security violation.

Instead, configure the MCP server definition in .mcp.json to ingest secrets via environment variable interpolation (${VAR_NAME}). Instruct developers to define the actual secret values inside their local .env files (which are git-ignored) or import them securely from an enterprise secret manager at runtime.

2. Enforce Boundary Approvals for Project Tools

When a developer clones a repository containing a .mcp.json file, Claude Code implements a trust boundary. Because project-scoped MCP servers execute local code and terminal commands, Claude Code will prompt the developer to explicitly authorize and trust the workspace's local .mcp.json servers before executing them.

Never instruct developers to use global command-line bypass flags (like automatically trusting all local scripts) across enterprise repositories. The authorization prompt is a vital programmatic check designed to prevent malicious dependencies or untrusted external pull requests from executing unauthorized code on a developer's machine.

CCAR-F Exam Strategy: Architecture Scenarios

On the Claude Certified Architect – Foundations (CCAR-F) exam, you will encounter complex scenario items testing your ability to deploy Claude Code across hundreds of developers without sacrificing security or developer velocity.

When evaluating these scenario questions, watch out for distractor options that suggest storing shared team database credentials inside global user profiles, or instructing developers to manually install complex local MCP dependencies without version-controlled configurations.

The architecturally sound solution always involves isolating secrets to local runtime variables while committing a clean, standardized .mcp.json definitions file directly to the project root. To master these configuration patterns and practice debugging multi-layered workspace hierarchies before test day, engineering leads routinely utilize specialized study platforms like ccaftraining.com to drill blueprint-aligned scenario challenges.

By strictly separating global personal preferences from shared repository tooling, you build an automated, highly secure AI development environment that scales effortlessly across your entire enterprise engineering organization.