Claude Code config.json: Complete Configuration Guide

Claude Code config.json: Complete Configuration Guide

Many developers search for Claude Code config.json when setting up Anthropic's coding assistant. If you've worked with tools like ESLint, TypeScript, Prettier, or VS Code, looking for a config.json file feels natural.

However, Claude Code does not use a file named config.json for its primary configuration. Instead, it relies on several settings.json files that operate at different scopes, along with .mcp.json for project-specific MCP server definitions.

Understanding this distinction is important because using the wrong configuration file can lead to settings being ignored, permission rules not applying, or team members using inconsistent configurations.

In this guide, you'll learn:

• what developers actually mean when searching for Claude Code config.json
• where Claude Code stores its configuration files
• the difference between global, project, and local settings
• how configuration precedence works
• when to use .mcp.json
• configuration best practices recommended by Anthropic

By the end of this guide, you'll know exactly which configuration file to edit, where it should be stored, and how Claude Code combines multiple configuration sources into a single effective configuration.

Quick answer: Although many developers search for Claude Code config.json, the official configuration file is settings.json, stored in user and project configuration directories. Project-specific MCP server definitions are stored separately in .mcp.json.

Does Claude Code Use config.json?

The short answer is no.

Unlike many developer tools, Claude Code does not include a root config.json file for configuration. Instead, it uses a layered configuration system built around multiple settings.json files.

These files can exist at different scopes:

This architecture provides much more flexibility than a single configuration file.

For example, your organization can define security policies in the shared project configuration, while each developer can maintain their own personal preferences without creating merge conflicts or accidentally committing local changes.

This layered approach also enables enterprise deployments, where managed policies can override user-defined settings while still allowing limited customization where appropriate.

For developers coming from other ecosystems, it's helpful to think of "Claude Code config.json" as a search term rather than an actual filename. In practice, the configuration you're looking for is almost always stored in one of the official settings.json files.

Claude Code Configuration Files Explained

Claude Code uses multiple configuration files instead of a single config.json. Each file has a specific purpose, allowing you to separate organization-wide settings, shared project configuration, personal preferences, and MCP server definitions.

Understanding what each file does is essential because editing the wrong file can make it appear as though Claude Code is ignoring your configuration.

~/.claude/settings.json

This file contains your global user configuration.

Settings stored here apply to every Claude Code project on your machine unless they are overridden by a higher-priority configuration source.

Typical uses include:

• preferred model settings
• default permission rules
• environment variables
• output preferences
• notification settings
• default behavior across all projects

Because this file is stored in your home directory, it is personal to your workstation and should not be committed to Git.

.claude/settings.json

This is the shared project configuration.

Unlike the global configuration, this file belongs to a specific repository and is intended to be shared with the rest of the development team.

Common examples include:

• project-wide permission rules
• approved tool configurations
• shared environment settings
• project defaults
• team conventions

Since every developer working on the repository should use the same baseline configuration, this file is typically committed to source control.

.claude/settings.local.json

This file contains personal project settings.

Sometimes you need project-specific preferences that should not affect other developers. For example, you might enable additional logging, use a different model during testing, or temporarily allow a command while debugging.

Instead of modifying the shared configuration, these changes belong in settings.local.json.

This file is intentionally designed for local customization and is normally excluded from version control, allowing each developer to tailor Claude Code to their own workflow without creating unnecessary Git changes.

.mcp.json

The .mcp.json file serves a different purpose.

Rather than configuring Claude Code itself, it defines the Model Context Protocol (MCP) servers available to the current project.

Typical configuration includes:

• MCP server definitions
• transport configuration
• startup commands
• environment variables
• authentication parameters
• server-specific options

Keeping MCP server definitions separate from Claude Code settings makes configuration easier to maintain and allows projects to evolve independently from user preferences.

Important: If you're searching for Claude Code config.json, the configuration you need is almost always located in one of the settings.json files. The .mcp.json file is only used for configuring project MCP servers, not Claude Code's general behavior.

Configuration Precedence

One of Claude Code's most powerful features is its layered configuration system.

Instead of relying on a single configuration file, Claude Code combines settings from multiple sources. When the same setting appears in more than one location, the value from the higher-priority scope takes precedence.

This approach allows organizations to enforce security policies while still giving developers flexibility to customize their local environment.

The precedence order is:

1. Managed (enterprise) settings
2. User settings (~/.claude/settings.json)
3. Project settings (.claude/settings.json)
4. Local project settings (.claude/settings.local.json)

As Claude Code loads your workspace, it merges these configuration sources into a single effective configuration.

flowchart TD

A[Managed Settings]

B[User settings]

C[Project settings]

D[Local settings]

E[Effective Configuration]

A --> B
B --> C
C --> D
D --> E

Why Configuration Precedence Matters

Imagine your team shares the following project configuration:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob"
    ]
  }
}

Every developer working on the repository receives the same default permissions.

Now suppose you temporarily need to allow a specific Bash command while debugging.

Instead of editing the shared project configuration, you add the rule to your own local settings:

{
  "permissions": {
    "allow": [
      "Bash(git status)"
    ]
  }
}

Only your local environment changes.

Your teammates continue using the shared configuration, and there is no risk of accidentally committing temporary permission changes to Git.

Enterprise Policy Overrides

Organizations using Claude Code Enterprise can define managed settings that apply across all developers.

These settings typically enforce security requirements such as:

• approved MCP servers
• blocked shell commands
• required permission prompts
• organization-wide defaults
• security restrictions

Managed policies exist specifically to prevent local users from bypassing important security controls.

For example, an enterprise administrator may prohibit unrestricted Bash execution across the company. Even if a developer attempts to allow it in their personal configuration, the managed policy continues to enforce the restriction.

This layered model provides a balance between developer flexibility and organizational security, making Claude Code suitable for both individual developers and large engineering teams.

Best practice: Store team-wide defaults in .claude/settings.json, keep personal preferences in settings.local.json, and avoid modifying shared configuration for temporary experiments or debugging.

What Can You Configure in settings.json?

The settings.json file controls much more than basic preferences. It is the central place for configuring how Claude Code behaves, what it is allowed to do, and how it interacts with your development environment.

Claude Code organizes its configuration into several categories, allowing developers to manage permissions, environment variables, project behavior, integrations, and user preferences through a consistent configuration system.

Permissions

The permissions section determines which operations Claude Code can perform automatically and which require your approval.

Typical configuration includes:

• tool permissions
• Bash command rules
• file system access
• network operations
• MCP tool permissions

For example, you can allow harmless read-only operations while requiring confirmation before executing shell commands or modifying files.

If you want a complete explanation of permission modes, rule matching, and security recommendations, see our Claude Code MCP Permissions guide.

Environment Variables

Claude Code can pass environment variables to commands and integrations.

This is useful when working with:

• API keys
• development environments
• testing tools
• MCP servers
• custom scripts

Instead of hardcoding sensitive values into repositories, environment variables allow configuration to remain portable while keeping secrets separate from source code.

Model Behavior

Configuration files can also influence how Claude Code behaves while assisting you.

Depending on the available settings, this may include options related to:

• model selection
• reasoning behavior
• output preferences
• feature flags
• experimental capabilities

As Claude Code evolves, new configuration options may become available without changing the overall configuration structure.

Notifications

Claude Code can generate notifications for certain events during development.

Examples include:

• completed tasks
• permission requests
• long-running operations
• workflow completion

Notification preferences help developers reduce interruptions while still staying informed about important actions.

MCP Integration

Although MCP servers are defined in .mcp.json, their interaction with Claude Code is closely connected to the overall configuration.

Your configuration determines, for example:

• whether MCP tools require approval
• which server actions are allowed
• how permissions are evaluated
• how Claude interacts with external tools

This separation keeps Claude Code settings focused on behavior while .mcp.json describes the external services available to the project.

Why Everything Isn't Stored in One File

Many developers initially expect a single config.json containing every possible option.

Claude Code intentionally separates configuration into multiple files because they serve different audiences:

• global preferences belong to the individual developer
• project settings belong to the repository
• local settings belong only to the current developer
• MCP definitions belong to the project infrastructure

This design reduces merge conflicts, improves security, and makes configuration easier to maintain as projects grow.

Rather than creating one large configuration file, Claude Code organizes settings according to ownership and responsibility, making it much easier for teams to collaborate safely.

Complete Configuration Examples

The following examples demonstrate how Claude Code configuration is typically organized across different configuration scopes. They are intended as starting points and should be adapted to your own workflow.

These examples intentionally show only the most common configuration patterns. Refer to the official Claude Code documentation for the complete schema and newly introduced options.

Example 1: Global User Configuration (~/.claude/settings.json)

Use this file for preferences that should apply to every Claude Code project on your machine.

{
  "permissions": {
    "allow": [
      "Read",
      "Glob"
    ],
    "ask": [
      "Bash"
    ]
  }
}

Typical use cases:

• default permissions across all projects
• personal preferences
• workstation-wide configuration

Example 2: Shared Project Configuration (.claude/settings.json)

Store configuration that every contributor to the repository should use.

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Edit"
    ]
  }
}

Typical use cases:

• shared permission rules
• project-wide defaults
• team conventions

This file is typically committed to Git, so everyone works with the same baseline configuration.

Example 3: Personal Project Configuration (.claude/settings.local.json)

Use this file for temporary or personal overrides that should not be shared with the team.

{
  "permissions": {
    "allow": [
      "Bash(git status)"
    ]
  }
}

Typical use cases:

• temporary debugging permissions
• personal workflow preferences
• local experimentation

This file is intended for local development and is normally excluded from version control.

Example 4: Project MCP Configuration (.mcp.json)

Unlike the previous files, .mcp.json defines the MCP servers available to the current project rather than configuring Claude Code itself.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    }
  }
}

Typical use cases:

• project MCP server definitions
• transport configuration
• startup commands
• server-specific environment variables

Keep Claude Code behavior in settings.json and project integrations in .mcp.json. Separating these responsibilities makes configuration easier to understand and maintain.

Common Configuration Mistakes

Most Claude Code configuration problems are not caused by bugs—they're the result of editing the wrong file, misunderstanding configuration precedence, or expecting behavior that doesn't match how the configuration system works.

Knowing the most common mistakes can save hours of troubleshooting.

Editing the Wrong Configuration File

The most common mistake is searching for or creating a config.json file.

Claude Code doesn't read a file with that name. If you create one, it will simply be ignored.

Instead, use the appropriate official configuration file:

• ~/.claude/settings.json for global settings
• .claude/settings.json for shared project settings
• .claude/settings.local.json for personal project preferences
• .mcp.json for project MCP server definitions

If Claude Code appears to ignore your changes, the first thing to verify is that you're editing the correct file.

Forgetting About Configuration Precedence

Another frequent issue is assuming that only one configuration file exists.

For example, you may update your global settings and wonder why nothing changes.

The reason is often that the current project contains its own configuration, which overrides the global value.

Similarly, enterprise-managed settings may override both project and user settings.

When troubleshooting unexpected behavior, always consider whether a higher-priority configuration source is taking precedence.

Committing Local Settings to Git

The purpose of settings.local.json is to store personal configuration.

Examples include:

• temporary permission rules
• debugging preferences
• experimental features
• local development settings

These changes are intended for your own environment and generally shouldn't be shared with the rest of the team.

If personal settings are accidentally committed, other developers may inherit configuration that was never meant to become part of the project.

As a best practice, keep shared defaults in .claude/settings.json and reserve settings.local.json for developer-specific customization.

Mixing Claude Code Configuration with MCP Configuration

Another common misunderstanding is treating .mcp.json as a replacement for settings.json.

These files serve different purposes.

settings.json controls how Claude Code behaves.

.mcp.json defines which MCP servers are available to the project.

Trying to configure permissions, models, or Claude Code behavior inside .mcp.json won't have the intended effect because those settings belong in settings.json.

Granting Excessively Broad Permissions

Developers sometimes create very broad permission rules to avoid confirmation prompts.

While this can improve convenience, it also increases the impact of mistakes, prompt injection attacks, or malicious repositories.

A better approach is to grant only the permissions that are actually required for your workflow.

Specific rules are easier to review, easier to audit, and significantly safer than blanket permissions.

If you're unsure how to structure permission rules securely, see our Claude Code MCP Permissions guide for practical recommendations and real-world examples.

Best practice: If Claude Code isn't behaving as expected, verify the configuration file location, check configuration precedence, and confirm you're editing the correct file before assuming there's a bug.

Claude Code Configuration Best Practices

Whether you're working on a personal project or managing hundreds of developers in an enterprise environment, following a few configuration best practices will make Claude Code easier to maintain, more secure, and more predictable.

Keep Shared Configuration Minimal

Only commit settings that every developer should use.

Examples include:

• approved MCP servers
• shared permission rules
• project defaults
• common environment configuration

Avoid storing personal preferences in the shared project configuration, as they often create unnecessary Git changes and confusion for other contributors.

Use Local Settings for Personal Preferences

Every developer works differently.

Some prefer additional logging, others temporarily enable debugging tools or experiment with new features.

These settings belong in:

.claude/settings.local.json

Keeping personal preferences separate from the shared project configuration helps maintain a clean repository while allowing each developer to customize their own workflow.

Follow the Principle of Least Privilege

One of the most important security recommendations is to grant only the permissions Claude Code actually needs.

For example, instead of allowing every Bash command, consider permitting only specific commands required for your workflow.

A narrowly scoped permission policy:

• reduces the impact of prompt injection
• limits accidental command execution
• improves security reviews
• makes permission rules easier to understand

Small, explicit permission rules are almost always preferable to broad allow lists.

Version Control Shared Configuration

Project configuration should be treated like application code.

Review configuration changes through pull requests, discuss significant permission changes with the team, and maintain a history of why configuration decisions were made.

This makes onboarding easier and reduces configuration drift across environments.

Document Custom Configuration

If your project requires unusual settings or custom MCP servers, document them alongside your repository.

A short explanation in your README or internal documentation can save new contributors considerable time and reduce setup mistakes.

Good documentation should explain:

• why a setting exists
• when it should be changed
• who is responsible for maintaining it
• whether it affects every developer or only specific environments

Review Configuration Regularly

As projects evolve, configuration often accumulates outdated rules that are no longer necessary.

Schedule periodic reviews to remove:

• obsolete permission rules
• unused MCP server definitions
• deprecated configuration options
• temporary debugging settings
• experimental features that are no longer used

Keeping configuration files small and intentional makes them significantly easier to audit and maintain.

Best practice: Treat Claude Code configuration as part of your project's architecture—not just a collection of settings. Well-organized configuration improves security, onboarding, collaboration, and long-term maintainability.

Frequently Asked Questions

Does Claude Code have a config.json file?

No. Claude Code does not use a file named config.json for its primary configuration.

Many developers search for "Claude Code config.json" because numerous developer tools use that naming convention. In Claude Code, however, the official configuration files are settings.json, located at the user, project, and local scopes.

Where is Claude Code configured?

Claude Code supports multiple configuration scopes:

• ~/.claude/settings.json for global user settings
• .claude/settings.json for shared project configuration
• .claude/settings.local.json for personal project settings
• .mcp.json for project-specific MCP server definitions

Each serves a different purpose and contributes to the final effective configuration.

What is the difference between settings.json and .mcp.json?

These files solve different problems.

settings.json controls how Claude Code behaves, including permissions, preferences, environment variables, and other configuration options.

.mcp.json defines which Model Context Protocol (MCP) servers are available within a project, along with their connection details.

Think of settings.json as configuring Claude Code itself, while .mcp.json configures the external tools Claude Code can use.

Which configuration file should I edit?

It depends on what you're trying to accomplish.

Use:

• ~/.claude/settings.json for settings you want across every project.
• .claude/settings.json for configuration shared with your team.
• .claude/settings.local.json for personal project preferences.
• .mcp.json when adding or modifying project MCP servers.

Editing the correct file ensures your changes are applied as expected and remain scoped appropriately.

Can I share the Claude Code configuration with my team?

Yes.

The recommended approach is to commit .claude/settings.json to your repository so everyone starts with the same project configuration.

Personal preferences, temporary debugging settings, and machine-specific customizations should remain in .claude/settings.local.json, which is intended for local use.

What happens if the same setting exists in multiple files?

Claude Code follows a configuration precedence hierarchy.

Higher-priority configuration sources override lower-priority ones when they define the same setting.

This allows organizations to enforce managed policies while still giving developers flexibility to customize their local environments where appropriate.

Should I create a config.json file?

No.

Although many developers search for "Claude Code config.json," creating a file with that name has no effect because Claude Code does not read it.

Always use the official configuration files documented by Anthropic.

Conclusion

Although Claude Code config.json is a common search query, the official configuration system is built around settings.json and .mcp.json, each serving a distinct purpose.

Once you understand the different configuration scopes, the system becomes straightforward. Global settings apply across all projects, project settings establish shared team defaults, local settings keep personal preferences separate, and MCP server definitions remain isolated in their own configuration file.

This layered design offers several advantages over a single configuration file. It improves collaboration, reduces merge conflicts, supports enterprise policy enforcement, and makes it easier to maintain secure, predictable development environments.

Whether you're configuring Claude Code for personal use or deploying it across a large engineering organization, following the official configuration structure will help you avoid common mistakes and ensure your settings behave as intended.

If you'd like to learn more about access control, read our Claude Code MCP Permissions guide to understand how allow, ask, and deny rules work, how permission precedence is evaluated, and how to build secure configurations for real-world projects.