### Preflight Checklist - [x] I have searched [existing requests](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20label%3Aenhancement) and this feature hasn't been requested yet - [x] This is a single feature request (not multiple features) ### Problem Statement User-scoped MCP servers are stored in `~/.claude.json`, a runtime state file also holding session caches, OAuth tokens, and 40+ machine-managed keys. This makes MCP configuration: - Invisible to dotfiles/config manage

[FEATURE] Support MCP server configuration in ~/.claude/settings.json (user-managed file)

Status Open

Maintainer reply None cached

Activity 10 comments · opened Mar 8, 2026

Preflight Checklist

[x] I have searched existing requests and this feature hasn't been requested yet
[x] This is a single feature request (not multiple features)

Problem Statement

User-scoped MCP servers are stored in ~/.claude.json, a runtime state file also holding session caches, OAuth tokens, and 40+ machine-managed keys. This makes MCP configuration:

Invisible to dotfiles/config managers — the file cannot be safely symlinked or version-controlled
Silently lost on Claude Code updates, reinstalls, or state resets

There is no stable, user-editable path for persistent user-scoped MCP configuration.

Proposed Solution

Support mcpServers in ~/.claude/settings.json, the existing user-managed config file. Same schema as .mcp.json, with env var interpolation already supported:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
      }
    },
    "brave_search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

~/.claude.json could retain backwards compatibility; settings.json takes precedence or merges.

Alternative Solutions

Current workaround: a shell wrapper that re-injects MCP config from a separate file into ~/.claude.json before every invocation — requires jq, breaks on schema changes.

Priority

High - Significant impact on productivity

Feature Category

MCP server integration

Use Case Example

Engineer manages their environment via a dotfiles repo (symlinks, version control)
They symlink ~/.claude/settings.json from the repo
MCP servers defined there are immediately available across all machines and reinstalls
No shell wrappers, no jq merging, no silent config loss

Additional Context

~/.claude/settings.json already supports env var interpolation — the infrastructure is in place
Comparable tools use dedicated, stable config files: Goose (~/.config/goose/), Kiro (~/.kiro/agents/)
Related: #5024 (~/.claude.json bloat), #11085 (persistent MCP enable/disable)

View original on GitHub ↗

8 Comments

joseandgoose · 5 months ago

+1 — ran into this directly when trying to disable cloud-synced MCP servers (Notion, ClickUp) on a specific device (headless Linux server) without affecting other machines on the same account.

Attempted workaround: added disabledMcpServers to ~/.claude/settings.json with both the internal names (claude_ai_Notion) and display names (claude.ai Notion). Neither had any effect — the servers remained connected and continued loading ~30K tokens of tool schemas on every session start.

The core issue: there is no supported way to opt out of cloud-synced MCP servers on a per-device basis. settings.json is the right place for this. A disabledMcpServers key (or equivalent) that works for cloud-synced servers would solve it without requiring users to fully disconnect a connector from their account.

senseihaiku · 5 months ago

JoeBerg8 · 5 months ago

joshsilb · 5 months ago

bluesky8318 · 5 months ago

craigeddy · 5 months ago

Since Claude Chat told me I should file an Issue and gave the text for my (probably duplicate of this one) issue:

Problem

There's currently no clean way to configure MCP servers that require secrets (e.g. API keys)
specifically for the Claude Code web/cloud environment without also affecting local desktop
Claude Code sessions.

The .mcp.json project file is shared via version control, which means:

Putting secrets directly in it is a non-starter
Using ${ENV_VAR} substitution works in the cloud environment (via Environment Variables

in the cloud settings UI), but requires every desktop user to also set that variable locally
or Claude Code warns/fails on startup

Duplicate server entries (one user-scoped, one project-scoped) have undefined/unpredictable

collision behavior

The cloud environment settings UI already has Environment Variables and a Setup Script —
but no MCP server configuration.

Requested Feature

Add an MCP server configuration section to the cloud environment settings UI (alongside
Environment Variables and Setup Script). This would allow teams to define MCP servers that
are only active in cloud sessions, keeping secrets out of version-controlled .mcp.json
and avoiding conflicts with local developer configurations.

Current Workaround

Developers must either accept the env var warning, manage per-user local config manually,
or avoid using MCP servers that require secrets in the cloud environment entirely.

patmandenver · 3 months ago

yjydist · 2 months ago

Showing cached comments. Read the full discussion on GitHub ↗