Skip to content

CowboyLogic/ai-dev / skills/client-config-claudecode

client-config-claudecode

Flagged

Manage and maintain Claude Code configuration files and settings. Use this skill whenever the user wants to view, edit, add, remove, or understand any Claude Code settings — permissions, hooks, MCP servers, environment variables, model settings, sandbox, auto mode, or any other configuration field. Trigger on: "add permission", "allow tool", "deny tool", "configure hook", "add MCP server", "change model", "update settings", "show my settings", "what settings do I have", or "set default mode".

FileKindSize
CHANGELOG.mdmarkdown18.3 KB
README.mdmarkdown3.2 KB
SKILL.mdskill md8.5 KB
assets/sources.jsonconfig3.2 KB
evals/evals.jsonconfig10.2 KB
references/hooks.mdmarkdown28.0 KB
references/mcp.mdmarkdown16.1 KB
references/permissions.mdmarkdown21.6 KB
references/settings-schema.mdmarkdown39.2 KB
scripts/show-settings.pyscript8.6 KB
scripts/update-references.pyscript5.4 KB
scripts/validate-settings.pyscript35.9 KB

references/mcp.md

View on GitHub
# MCP Servers Reference

Upstream: `https://code.claude.com/docs/en/mcp.md` (managed config: `https://code.claude.com/docs/en/managed-mcp.md`).

## File locations (installation scopes)

| Scope | Loads in | Stored in |
|-------|----------|-----------|
| Local (default for `claude mcp add`) | Current project only, private | `~/.claude.json` → `projects["/abs/path"].mcpServers` |
| Project (shared via git) | Current project | `.mcp.json` in project root → `mcpServers` |
| User | All your projects | `~/.claude.json` → top-level `mcpServers` |
| Managed | Everyone | `managed-mcp.json` in the managed system dir, or the `managedMcpServers` managed setting |

> [!NOTE]
> MCP servers are NOT configured in `settings.json` — they live in `~/.claude.json` (local/user scope) or `.mcp.json` (project scope). "Local scope" for MCP is unrelated to `.claude/settings.local.json`.

**Precedence when the same server is defined twice** (whole entry wins, no field merge): local → project → user → plugin-provided → claude.ai connectors. A `managedMcpServers` entry ranks above all of them (v2.1.259+). Scopes match duplicates by name; plugins/connectors match by endpoint.

Prefer the CLI over hand-editing:

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp                # local scope
claude mcp add --transport http shared --scope project https://example.com/mcp  # writes .mcp.json
claude mcp add --transport stdio --env API_KEY=xxx airtable -- npx -y airtable-mcp-server
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp"}' --scope user
claude mcp list
claude mcp get <name>
claude mcp remove <name>
claude mcp reset-project-choices                 # reset .mcp.json approvals
```

`--` separates Claude's options from the stdio server command.

---

## ~/.claude.json mcpServers structure (user scope)

```json
{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
```

---

## Transport types

### stdio (local process)

```json
{
  "type": "stdio",
  "command": "node",
  "args": ["path/to/server.js"],
  "env": { "API_KEY": "..." }
}
```

### HTTP (streamable HTTP — recommended for remote)

```json
{
  "type": "http",
  "url": "https://mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
}
```

`"streamable-http"` is accepted as an alias for `"http"`.

### SSE (deprecated)

```json
{
  "type": "sse",
  "url": "https://mcp.example.com/sse",
  "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
}
```

SSE is deprecated; `claude mcp add --transport http` falls back to SSE automatically when the server doesn't accept HTTP (v2.1.265+).

### WebSocket

```json
{
  "type": "ws",
  "url": "wss://mcp.example.com/socket",
  "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
}
```

Configure only via `.mcp.json` or `claude mcp add-json` (`--transport` doesn't accept `ws`). Header auth only (no OAuth).

A JSON entry with a `url` but no `type` is an error — Claude Code reads it as stdio and skips the server. Server names may contain only letters, numbers, hyphens, and underscores.

**Other per-server fields**:

- `timeout` — per-server tool-call timeout in ms (values < 1000 ignored; overrides `MCP_TOOL_TIMEOUT`). Startup timeout is the `MCP_TIMEOUT` env var.
- `headersHelper` — script that generates auth headers at connect time (project `.mcp.json` helpers run only after workspace trust).
- `alwaysLoad` — `true` skips tool-search deferral (all the server's tools load at session start; valid on every server type, `ws` included); `false` keeps all of the server's tools deferred (v2.1.287+). See [Tool loading, limits, and runtime](#tool-loading-limits-and-runtime).
- `oauth` — `{clientId, callbackPort, authServerMetadataUrl, scopes}`; pass a secret with `claude mcp add-json ... --client-secret`.

`widgets` is a reserved server name in cloud sessions and on self-hosted runners: a server of that name, or a close spelling such as `widgets_`, no longer loads, so rename it (v2.1.285; changelog only).

Stdio servers receive `CLAUDE_PROJECT_DIR` (project root) in their environment. Referencing it in `command`/`args` of `.mcp.json` or `~/.claude.json` entries needs a default: `${CLAUDE_PROJECT_DIR:-.}` (plugin configs substitute it directly).

### Environment variable expansion

`${VAR}` and `${VAR:-default}` expand in `command`, `args`, `env`, `url`, and `headers`. An unset variable with no default is left as literal `${VAR}` with a warning in `claude mcp list`. In a remote server's `url`/`headers`, credential variables such as `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `AWS_BEARER_TOKEN_BEDROCK`, `HTTPS_PROXY`, and `NPM_TOKEN` always read as empty — copy the value into a variable with your own name.

---

## Tool loading, limits, and runtime

Tool search is on by default: a server's tools are deferred and found on demand. With `ENABLE_TOOL_SEARCH` unset, Claude Code falls back to loading every MCP tool upfront on a Microsoft Foundry deployment hosted on Azure and on Google Cloud Agent Platform models earlier than the Claude 4.5 generation; `ENABLE_TOOL_SEARCH=true` does not override those two cases. Behind an `ANTHROPIC_BASE_URL` gateway, tool search is on by default from v2.1.304 (before that it was off unless `ENABLE_TOOL_SEARCH` was `true`, `auto` or `auto:N`); from v2.1.305 a request that gets a `400` or `422` whose cause Claude Code does not recognize is retried without tool search, so MCP tools load upfront, and `ENABLE_TOOL_SEARCH=false` skips those rejected requests. Setting `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` keeps tool search off and `ENABLE_TOOL_SEARCH` cannot override it; managed settings can keep tool search on (v2.1.227+). The `ENABLE_TOOL_SEARCH` values are in the [MCP docs](https://code.claude.com/docs/en/mcp#configure-tool-search).

- **`alwaysLoad: true`** (server entry) loads all of that server's tools upfront. Startup then waits for the server's tools, capped at the 5-second connect timeout, unless a valid `cached` entry supplies them. Other servers connect in the background; `MCP_CONNECTION_NONBLOCKING=0` makes startup wait for them too.
- **`alwaysLoad: false`** (server entry) defers every tool of that server, including tools its author marked to load upfront (v2.1.287+).
- **Per-tool `_meta["anthropic/alwaysLoad"]`** (set by the server author): `true` loads that tool upfront. `false` keeps it deferred when the user's config sets `alwaysLoad: true` for a server passed with `--mcp-config`, supplied by an Agent SDK app, or provided by a plugin (v2.1.285+).
- **Description limits**: tool descriptions sent up front and each server's instructions are truncated at a default character limit; `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` (v2.1.280+) sets it for every server. The MCP docs page states the default as 2,048 characters; the v2.1.296 changelog says the default for tool descriptions sent up front and for server instructions changed from 2,048 to 4,096, so treat the docs page as lagging. Per the v2.1.295 changelog, tool descriptions loaded through tool search are cut at 16,384 characters.
- **Retry failed servers**: `/mcp reconnect all` retries every server that failed or needs authentication. In the interactive terminal it needs v2.1.284+; earlier versions print `MCP server "all" not found`.
- **Client runtime**: Claude Code picks the v1 or v2 MCP client runtime at startup. `MCP_SDK_GENERATION` (`v1` | `v2`) forces one. `MCP_PROTOCOL_NEGOTIATION` (`auto` | `legacy`) decides whether Claude Code asks servers for protocol revision 2026-07-28; `legacy` keeps every server on the earlier handshake.
- **MCP tasks** (MCP docs page): when a server supports tasks and runs a tool call as a task, Claude Code moves it to the background and tells Claude the result when it finishes. The call must come from the main conversation on a server connected on protocol revision 2026-07-28, in a session that fetches feature flags (the docs page says not Bedrock, not telemetry or flag fetching off; changelog only, v2.1.319: MCP tasks now work in the terminal without feature-flag fetching, including Bedrock, Vertex, Foundry, LLM gateways and `DISABLE_TELEMETRY`, and `CLAUDE_CODE_DISABLE_MCP_TASKS=1` turns them off, so the docs page lags on this condition), in a terminal, Agent SDK or GitHub Actions session (not VS Code or desktop). `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1` makes Claude wait for the task instead (v2.1.319 per the changelog; the docs page lists the variable); `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0` makes it wait for every MCP call.
- **MCP task questions** (changelog only, v2.1.325): when a background MCP task asks you a question, Claude is told it is waiting for your answer and can point you to `/tasks`; Esc on the question now means "answer later" (nothing is sent to the server and the question stays in `/tasks`), and the question waits until you send or clear a draft you are typing.
- **Stdio handshake probe** (changelog only, v2.1.318): a stdio server that exits on the version probe is no longer re-probed on every start; one that dies in under 3 seconds for its own reason is pinned to the legacy handshake for 7 days. Changelog only (v2.1.319): servers on the older handshake no longer fail to connect or return empty results because Claude Code declared an extension it only uses with newer servers.
- **Empty `AWS_BEARER_TOKEN_BEDROCK`** (changelog only, v2.1.317): a stdio server whose `env` sets it to empty now has the variable unset, so the server can use the machine's own AWS credentials.
- **URL elicitation** (changelog, v2.1.287): servers on the 2025-11-25 protocol can send URL prompts. A server that stops connecting after that update can be given `"bareElicitationCapability": true` in its config entry. This key is not in the MCP docs page.
- **WebSocket limit** (changelog, v2.1.295): a `ws` message over 16 MiB is no longer parsed and closes the connection, the same limit the other transports already have.
- **Tool schemas and names** (MCP docs page): a tool whose input schema has `anyOf`, `oneOf` or `allOf` at the root is flattened into one object schema with a sentence prepended to its description (a `oneOf`/`anyOf` branch's `required` list is described, not enforced, so the server must keep validating the combination); on a deployment that does not receive the remote configuration enabling the rewrite, or when no valid schema can be produced, Claude Code skips that one tool and logs the reason. A tool with an invalid schema (a top-level property name outside 1–64 ASCII letters, digits, `_`, `.`, `-`, or, for a schema that declares no `$schema` or declares draft 2020-12, a failure of the draft 2020-12 meta-schema; a schema declaring another dialect skips that check but still gets the property-name check) is excluded and the reason goes to the server's log, so one bad tool does not break the server's other tools; the exclusion is switched on by a flag Claude Code fetches, so with flag fetching off the tool is still sent and the API answers with a 400. A tool whose full name is over 128 characters is left out. Changelog only (v2.1.300): when the API still rejects a tool's input schema, Claude Code sends that tool without parameters for the rest of the conversation instead of failing every turn with a 400.

---

## Examples from the upstream docs

```bash
# GitHub remote server with a PAT
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# PostgreSQL via DBHub (use a read-only DB user)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
```

---

## MCP settings in settings.json

These control MCP behavior; the servers themselves are in `~/.claude.json` / `.mcp.json`:

```json
{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["memory", "github"],
  "disabledMcpjsonServers": ["filesystem"],
  "allowedMcpServers": [{ "serverName": "github" }],
  "deniedMcpServers": [{ "serverName": "filesystem" }],
  "allowManagedMcpServersOnly": true,
  "disableClaudeAiConnectors": true,
  "allowAllClaudeAiMcps": true
}
```

| Setting | Effect |
|---------|--------|
| `enableAllProjectMcpServers` | Auto-approve all project `.mcp.json` servers |
| `enabledMcpjsonServers` | Approve specific servers from `.mcp.json` |
| `disabledMcpjsonServers` | Block specific servers from `.mcp.json` |
| `allowedMcpServers` | Allowlist (any file; entries merge unless `allowManagedMcpServersOnly`). Each entry has exactly one of `serverName`, `serverCommand`, `serverUrl`; `[]` blocks every user-added server. `managed-mcp.json` servers need no entry; the allowlist checks one only when it uses `${VAR}` expansion outside `env` (v2.1.305+; before that it also checked servers using `${VAR}` only in `env`, so a server your allowlist left out starts loading on upgrade; add `deniedMcpServers` entries to keep it off) |
| `deniedMcpServers` | Denylist (any file; always merges). Same entry shape; `serverName` can name a connector such as `"claude.ai Slack"`. Changelog only (v2.1.318): `serverUrl` entries also block Anthropic-provided servers whose upstream URL matches, and connectors in cloud sessions and on self-hosted runners, where the session is given the connector's own URL; to deny a connector otherwise, deny it by name |
| `allowManagedMcpServersOnly` | (managed) Only managed servers allowed |
| `disableClaudeAiConnectors` | Disable claude.ai connectors entirely. Any-source-true: a `true` in any scope wins over a `false` elsewhere. `--mcp-config` servers unaffected |
| `allowAllClaudeAiMcps` | (managed) Load claude.ai connectors alongside a deployed `managed-mcp.json`, which otherwise suppresses them |
| `allowClaudeInChromeWithManagedMcp` | (managed, on-machine) Let the built-in Claude in Chrome server run alongside a deployed `managed-mcp.json`, which otherwise blocks it in terminal sessions (v2.1.282+) |
| `managedMcpServers` | (managed) Provide remote `http`/`sse` servers (`https://` URL required) to every user; users can't edit/remove them (v2.1.259+) |

`enableAllProjectMcpServers` and `enabledMcpjsonServers` in a repo's `.claude/settings.json` are ignored until you trust the folder. `claude -p`, SDK, and cloud sessions load `.mcp.json` servers without asking — use `disabledMcpjsonServers`, `--setting-sources`, or `--strict-mcp-config` to keep one out.

**Per-project on/off toggles** in `/mcp` are stored in `~/.claude.json` as `disabledMcpServers` (opt-out list) and `enabledMcpServers` (opt-in, for default-off built-ins like `computer-use`) — unrelated to `enabledMcpjsonServers`/`disabledMcpjsonServers`.

---

## MCP permission rules (in settings.json permissions)

```json
{
  "permissions": {
    "allow": ["mcp__github__*"],
    "deny": ["mcp__filesystem__write*"],
    "ask": ["mcp__puppeteer__*"]
  }
}
```

Pattern: `mcp__<server-name>__<tool-name>` (bare `mcp__<server>` also matches all its tools, except for a server whose name contains `__` or ends in `_`: write `mcp__<whole name>__*`, see `permissions.md`). Plugin-bundled servers use `mcp__plugin_<plugin-name>_<server-name>__<tool>`; claude.ai connectors use `mcp__claude_ai_<server>__<tool>`. Allow-rule globs need a literal `mcp__<server>__` prefix; `mcp__*` works only in deny/ask.

**Tools that force a prompt regardless of allow rules / permission mode:**

- Server marks a tool `_meta["anthropic/requiresUserInteraction"]: true` — always prompts (even `acceptEdits`/`auto`/`bypassPermissions`); denied outright in `dontAsk`.
- Org sets a claude.ai connector tool to `ask` (via admin console) — same forced-prompt behavior. Org can also set a tool to `blocked`, which filters it out before Claude ever sees it.

---

## Add a new MCP server

Prefer `claude mcp add` / `claude mcp add-json --scope user`. To hand-edit at user scope, add the entry to the top-level `mcpServers` object in `~/.claude.json` (not settings.json); local-scope servers live under `projects["<path>"].mcpServers` instead.

```bash
# View current MCP config
python3 -m json.tool ~/.claude.json
```

## Verify MCP servers are loaded

Inside Claude Code, type `/mcp` to see all configured servers and their status, or run `claude mcp list` / `claude mcp get <name>` from a shell.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall