Claude Code MCP Setup: Add Servers With claude mcp add, Pick the Right Scope, and Fix Connection Failures

Claude Code MCP setup, start to finish: add a stdio and an HTTP server, pick local, project or user scope, share .mcp.json safely, and fix failed connections.

Claude Code MCP setup precedence diagram: six stacked cards ranked from organization managedMcpServers at the top through local, project and user scope to plugin servers and claude.ai connectors, with an upward arrow labelled wins.Claude Code MCP setup precedence diagram: six stacked cards ranked from organization managedMcpServers at the top through local, project and user scope to plugin servers and claude.ai connectors, with an upward arrow labelled wins.
When one server name is defined in several places, Claude Code uses the whole entry from the highest source and merges nothing, so a local test copy shadows the team's .mcp.json until you remove it. Original diagram based on Anthropic's Claude Code MCP documentation, fetched Oct 21, 2026.

You added an MCP server to Claude Code, it worked once, and now /mcp shows a cross next to it, or the server is missing from the one repository where you need it. Many of those reports trace back to a question nobody answered at setup time: which configuration file owns this server? This Claude Code MCP setup guide answers it by building a small, real configuration from scratch. You will connect one local stdio server and one remote HTTP server, place each in a scope you chose on purpose, share a team .mcp.json that holds no secret, verify both, and finish with a symptom-to-fix table and a rollback you can run in two minutes.

The reader I have in mind is an individual developer with Claude Code installed on a Pro or Max subscription or a Console account. If the protocol itself is new to you, read our MCP explainer for power users first. This guide stays on the mechanics.

There is a dated reason to tidy this up now, but it is background, not the lesson. Anthropic’s Claude Code v2.1.306 release, published on GitHub on Oct 21, 2026, fixed “an API error being replaced by ‘prompt is too long’, and an unneeded compaction, in sessions with many MCP tools.” A day earlier, v2.1.305 fixed “an MCP server passed by a cloud session or by the SDK’s setMcpServers being replaced later in the session by a same-named server from your own settings.” Both bugs sit exactly where setup mistakes sit: which definition of a server loads, and how much tool context it costs.

GitHub release page for anthropics/claude-code v2.1.306 showing the release header and the What's changed list with two fixes
GitHub release page for Claude Code v2.1.306, published by Anthropic on Oct 21, 2026. The What's changed list includes the fix for an API error being replaced by 'prompt is too long', and an unneeded compaction, in sessions with many MCP tools. · Original source

A note on evidence before the first command. Everything below is documented syntax from Anthropic’s Claude Code MCP reference and CLI reference, plus OpenAI’s Codex configuration reference for the final section. We did not run these commands to capture output for this article, so the expected observations quote the status strings Anthropic documents rather than a terminal session we recorded. The database URL, the token and the server names are placeholders you replace with your own.

Top of Anthropic's Claude Code documentation page titled Connect Claude Code to tools via MCP
Anthropic's Claude Code MCP reference, 'Connect Claude Code to tools via MCP', captured from code.claude.com. The capture shows the top of the page; the scope, status and troubleshooting details used in this guide appear further down the same page. · Original source

What you will build, and what to have ready

By the end you will have two servers connected and verified, each in a scope you can name, plus a documented way to see, fix or remove either of them. The worked example uses servers that Anthropic’s own documentation uses as examples, so every command maps to a published reference:

Server name What it is Transport Scope you will use Where its credential lives
db DBHub (@bytebase/dbhub), a database MCP server launched with npx stdio local first, then project A read-only connection string: in ~/.claude.json while local, then in your shell as DBHUB_DSN
github GitHub’s remote MCP server HTTP user A fine-grained personal access token, in ~/.claude.json or an environment variable
sentry (optional) Sentry’s remote MCP server HTTP with OAuth project No secret in any file; each person signs in through /mcp

Why these choices? The database server holds a password and starts as a personal experiment, so it begins private and moves to the team file only after the secret has been pulled out into a variable. The GitHub token is yours alone and useful in every repository, which is the definition of user scope. Sentry shows the OAuth path, where the shared file can be committed as-is because sign-in happens per person and nothing sensitive is written to the repository.

Before you start, check off the following:

  • [ ] Claude Code is installed and claude --version prints a version number, as the Claude Code overview describes. Run claude update to move to the latest build; several behaviors in this guide arrived in recent v2.1 releases, and v2.1.306 is marked Latest at the time of writing.
  • [ ] You are signed in with a Claude subscription or an Anthropic Console account. Most Claude Code surfaces require one of the two.
  • [ ] You have a test repository under git, so every change to .mcp.json can be diffed and reverted.
  • [ ] Node.js with npx is installed, because the stdio server is launched through npx.
  • [ ] You can reach a development Postgres database with a read-only user. Anthropic’s DBHub example recommends a read-only user “so the queries Claude runs can’t modify data.”
  • [ ] You have generated a fine-grained GitHub token limited to the repositories Claude should see.
  • [ ] You have decided whether each server deserves your trust. The MCP reference warns that servers fetching external content “can expose you to prompt injection risk.” Our MCP hardening guide covers that review, and this guide does not repeat it.

If you are new to the CLI’s broader habits, such as CLAUDE.md files, hooks and permission modes, the Claude Code power user’s field guide is the companion read.

Pick a scope before you type the command

Every claude mcp add writes to one of three scopes, and the default is the one people forget. The MCP reference defines them this way:

Scope Loads in Shared with team Stored in
Local (default) Current project only No ~/.claude.json, under that project’s path
Project Current project only Yes, through version control .mcp.json in the project root
User All your projects No ~/.claude.json

Two details explain most “it disappeared” reports. First, local scope is keyed to the directory you ran the command in. Add a server from ~/code/api and it will not exist in ~/code/web. Second, the word “local” is overloaded. MCP local scope lives in ~/.claude.json in your home directory, while the general local settings file is .claude/settings.local.json inside the project. The settings documentation confirms that ~/.claude.json is a file Claude Code writes for itself, holding “your sign-in session, MCP server configurations, per-project state such as trust decisions.” You rarely need to open it, but you should know which servers it is quietly holding.

When the same name is defined in more than one place, Claude Code connects once, using the highest-precedence source, and “the entire server entry from that source is used; fields are not merged across scopes.” The order runs local, then project, then user, then plugin-provided servers, then claude.ai connectors. A server your organization provides through the managedMcpServers managed setting ranks above all of them on v2.1.259 or later. The three scopes are matched by name; plugins and claude.ai connectors are matched by endpoint, so a connector pointing at the same URL as one of your servers counts as a duplicate, and /mcp lists it as hidden.

Claude Code MCP setup precedence diagram: six stacked cards ranked from organization managedMcpServers at the top through local, project and user scope to plugin servers and claude.ai connectors, with an upward arrow labelled wins.Claude Code MCP setup precedence diagram: six stacked cards ranked from organization managedMcpServers at the top through local, project and user scope to plugin servers and claude.ai connectors, with an upward arrow labelled wins.
When one server name is defined in several places, Claude Code uses the whole entry from the highest source and merges nothing, so a local test copy shadows the team's .mcp.json until you remove it. Original diagram based on Anthropic's Claude Code MCP documentation, fetched Oct 21, 2026.

Administrators have one more recent change to note. v2.1.305 changed allowedMcpServers to stop filtering managed-mcp.json stdio servers that use ${VAR} only in env; a server the allowlist used to leave out now loads after the upgrade, and the release notes point to deniedMcpServers to keep it off.

Use this decision table for each server you add:

If the server… Choose Reason
Carries a credential you would never commit, or is still an experiment Local (no flag needed) Private to you and to this one project
Should appear for every teammate who clones the repository Project (--scope project) Written to .mcp.json, which you commit; each person approves it
Is a personal tool you want in every repository User (--scope user) One definition for all your projects
Already reaches you through your organization, a plugin or a claude.ai connector Do not add a copy A same-named or same-endpoint copy only creates a precedence puzzle

The rule that bites later: a local definition outranks a project definition with the same name. If you test a server locally and then commit it to .mcp.json, your machine keeps loading the local copy until you remove it, while your teammates load the committed one. Sharing is what project scope is for, but only after the private copy is gone. That is the setup-time cousin of the same-name replacement bug v2.1.305 fixed for SDK and cloud sessions, and it is why the precedence diagram is worth keeping beside you while you work.

Add the local stdio server with claude mcp add

A stdio server runs as a local process that Claude Code starts and talks to over standard input and output. The documented syntax is claude mcp add [options] <name> -- <command> [args...], and the double dash is the part that matters.

cd ~/code/test-repo
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/app_dev"

Work through it in order:

  1. Change into the repository first. Local scope records the server under the current project’s path, so the directory you stand in decides where the server exists.
  2. Run the command. Claude Code’s own options (--transport, --env, --scope) go before --; everything after -- is “passed to the server untouched.” Without the separator, Claude Code would try to read -y and --dsn as its own options.
  3. Read the result. A successful add prints an Added ... line, which means the configuration was written. If you see a was not saved or may not have been saved message instead, treat the configuration as unchanged and resolve that before going further.
  4. Inspect the entry with claude mcp get db. It shows the details Claude Code recorded for the server, including its status.
  5. Start claude in the repository and ask a read-only question such as “Show me the schema for the orders table.” That prompt comes from Anthropic’s own DBHub example, and a real table list is your proof that the whole path works.

Three choices in that command deserve a reason. The name db uses only letters, which matters because names added through claude mcp commands may contain only letters, numbers, hyphens and underscores, and several built-in names, including workspace and computer-use, are reserved and rejected by claude mcp add. npx -y keeps the launch non-interactive, because a stdio server has no way to answer an install prompt. And the connection string uses a read-only database user, so a confused prompt cannot write to your tables.

Many servers read a key from the environment instead of an argument. The documented pattern passes it with --env:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Note the order. --env accepts several KEY=value pairs, so if the server name comes directly after it, the CLI reads the name as another pair and rejects it. Put another option such as --transport stdio between them, or put the name first, as in the reference’s claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server.

Two runtime facts help if you write your own stdio server. Claude Code sets CLAUDE_PROJECT_DIR in the spawned server’s environment to the project root, so the server can resolve project paths without depending on its working directory. And when the session ends, Claude Code stops the process on a short clock: on macOS and Linux it sends SIGINT, then SIGTERM 100 milliseconds later if the process is still running, then SIGKILL after a further 400 milliseconds; on Windows it closes the server’s stdin and ends the process tree 300 milliseconds later. A server that must save state or remove lock files has to finish inside that window. Claude Code also does not reconnect stdio servers automatically; remote servers get retries, local processes do not, so a crashed stdio server stays down until you reconnect it.

Add the remote HTTP server with a header or OAuth

HTTP is the transport Anthropic recommends for remote servers, and it is the one that supports OAuth. Pick one of two authentication paths.

Path A: a token in a header. GitHub’s remote server authenticates with a personal access token passed as a header:

claude mcp add --transport http github --scope user \
  https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"
  1. Replace the placeholder with your fine-grained token, then run the command. --scope user makes the server available in every project on your machine.
  2. Expect an Added ... line. Be aware that claude mcp add “saves the configuration without validating credentials, so a placeholder value is accepted here but the server fails to connect later.”
  3. Open claude, run /mcp, and look for a checkmark on the github row. A bad token shows a cross instead, and the failure detail includes the HTTP status the server returned, such as a 401.
  4. Ask a read-only question taken from the documentation’s examples: “Show me all open PRs assigned to me.”

If you would rather keep the token value out of ~/.claude.json, store a variable reference and set the value in your shell. The single quotes stop your shell from expanding it, so Claude Code receives the reference and resolves it when it loads the server:

claude mcp add-json --scope user github \
  '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${MY_GITHUB_MCP_PAT}"}}'

Choose that variable name yourself. In a remote server’s url and headers, Claude Code deliberately reads a set of credential variables as empty, including its own ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN, cloud provider credentials, and others your environment carries, such as NPM_TOKEN. A header built from one of those reaches the server as Bearer with nothing after it and is usually rejected with a 401. A name outside that set, like the one above, expands as written.

One behavior surprises people on this path. When you configure the Authorization header yourself, a 401 or 403 while connecting is reported as a failed connection, not as “needs authentication,” and Claude Code does not fall back to OAuth. The credential to fix is the one you supplied, so look at the token before you look at the server.

Path B: OAuth through /mcp. Sentry’s server uses browser sign-in instead of a token you paste:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
  1. Add the server. Running the same command twice at the same scope fails with MCP server sentry already exists in local config, so remove or rename first if you are repeating the exercise.
  2. In a session, run /mcp and follow the steps in your browser. If the browser does not open, copy the URL Claude Code provides; if the redirect fails after you approve, paste the full callback URL from your browser’s address bar into the prompt Claude Code shows.
  3. From a shell, claude mcp login sentry runs the same flow without opening the panel. Over SSH, connect with ssh -t and add --no-browser so the command prints the authorization URL instead of trying to launch a browser.
  4. Confirm that the sentry row in /mcp no longer needs authentication. Claude Code stores the tokens and refreshes them automatically, and when a stored refresh token is rejected it points you back at /mcp to re-authenticate.

If sign-in fails with “Incompatible auth server: does not support dynamic client registration,” the server needs a pre-registered OAuth app. Register one in the server’s developer portal, then add the server with --client-id, --client-secret (which prompts with masked input) and a --callback-port that matches the registered http://localhost:PORT/callback redirect.

Share a project .mcp.json without committing secrets

Once db works for you, give it to the team. The committed file must carry the shape of the configuration, not the password. Claude Code expands ${VAR} and ${VAR:-default} in .mcp.json inside command, args, env, url and headers, which is exactly what you need here.

Create .mcp.json in the repository root:

{
  "mcpServers": {
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DBHUB_DSN}"]
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Then promote it step by step:

  1. Set DBHUB_DSN in your own shell environment, never in the repository. Each teammate sets their own value pointing at a database they are allowed to read.
  2. Remove your private copy with claude mcp remove db --scope local. Local outranks project, so skipping this step means your machine keeps running the old definition while everyone else runs the new one. If you added sentry at local scope in Path B, remove that copy the same way.
  3. Restart claude. Because the file is new, Claude Code prompts for approval in the interactive session before it uses the project-scoped servers. Approve both.
  4. Run claude mcp list and confirm both entries connect.
  5. Commit .mcp.json. On a teammate’s first run in a fresh clone, the servers show ⏸ Pending approval until they run claude interactively, accept the workspace trust dialog and approve.

A few file rules prevent quiet failures. An entry with a url but no type is a configuration error, because Claude Code reads an entry without type as a stdio server; it skips the entry and tells you to add "type": "http". The value streamable-http is accepted as an alias for http, so JSON copied from another client’s instructions usually works unchanged. An entry with "type": "sdk" is skipped, because only an SDK host application can register one. If a referenced variable is unset and has no default, the file still loads, but Claude Code warns about the missing variable in claude mcp list and /mcp and uses the literal ${DBHUB_DSN} text, which will not connect. And if a server needs the project root in command or args, write ${CLAUDE_PROJECT_DIR:-.}; that variable exists only in the server’s own environment, so the default is required.

Approval has two edges worth knowing. A cloned repository cannot approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed to the project’s .claude/settings.json is ignored until you trust the folder. In the other direction, claude -p runs, Agent SDK sessions and cloud sessions cannot show the prompt and load project-scoped servers without asking. If a repository you run headless might carry a server you do not want, block it with disabledMcpjsonServers, exclude project settings with --setting-sources, or start with --strict-mcp-config so only servers passed through --mcp-config load. Our restricted-mode fleet policy guide treats those flags as standing policy rather than per-session habits. A committed .mcp.json is also exactly how shadow MCP spreads through a team, so review changes to it in pull requests the way you review code.

Verify both servers with list, get, /mcp and a real call

Verification has several layers, and each catches something the others miss. The table quotes the statuses the MCP reference documents; it is not output captured for this article.

Check Command Healthy (documented) Unhealthy (documented) What it tells you
Was it written? claude mcp add Added ... was not saved, may not have been saved Whether the configuration changed at all
Does it connect? claude mcp list ✔ Connected ✘ Failed to connect with detail, ! Needs authentication, ⏸ Pending approval A failure status means that server failed, not the list command
Why not? claude mcp get db Server details and status An Issue: line with the HTTP status or error code, or ✘ Rejected The only place a rejected project server appears
Inside the session /mcp Checkmark and a tool count Cross, a disabled marker, or a flag for a server exposing no tools What Claude can actually use right now
Does it do work? A read-only prompt Real data comes back The No such tool available tool error The full path, including permissions

Matrix chart of where six Claude Code MCP statuses appear across claude mcp list, claude mcp get and the /mcp panel, with the Rejected row highlighted in amber because it appears only in claude mcp get.Matrix chart of where six Claude Code MCP statuses appear across claude mcp list, claude mcp get and the /mcp panel, with the Rejected row highlighted in amber because it appears only in claude mcp get.
A rejected .mcp.json server appears only in claude mcp get, so check there when claude mcp list shows nothing. Original chart of documented behavior from Anthropic's Claude Code MCP reference, fetched Oct 21, 2026; 'not stated' marks surfaces the docs do not describe, and no commands were run to capture output.

Two observations are easy to misread. A remote server you have used before can show a cached status in /mcp, such as cached 2h ago · connects on first use · 5 tools. That is normal when the discovery cache is on: the tool list comes from a previous session and the server connects the first time Claude calls one of its tools. And when a failure is reported, Claude Code redacts credential-like text and never prints the expanded server URL, so a missing token value in the message is a safety feature rather than a fault. A bare ✘ Connection error with no detail is deliberate for the same reason.

Finish with this checklist:

  • [ ] claude mcp list shows db and github, and sentry if you added it, as connected.
  • [ ] /mcp shows a tool count next to each server, not a flag for a server that advertises tools but exposes none.
  • [ ] “Show me the schema for the orders table” returns real tables from db.
  • [ ] “Show me all open PRs assigned to me” returns real pull requests from github.
  • [ ] claude mcp list prints no configuration warning about whitespace, missing variables or a name defined in more than one scope.

Once everything passes, record each server, its scope and its owner somewhere your team reads; the weekly MCP server inventory ritual is a good template for that record.

Symptom-to-fix table for failed MCP connections

Every row below is a cause the MCP reference documents. Work from the top; the earlier rows are cheaper to rule out.

Symptom Documented cause Fix
Server missing from claude mcp list in this repository Added at local scope from another directory Run from the original project, or re-add with --scope user or --scope project
MCP server db already exists in local config Same name at the same scope claude mcp remove db --scope local, then add again
stdio server never starts; the reference’s example error is spawn claude ENOENT The executable is not on your PATH Use the executable’s full path in the command
Server flags such as --dsn treated as Claude Code options Missing -- before the server command Re-add with -- between Claude’s options and the command
--env rejects the server name Name placed directly after --env Put --transport stdio between them, or put the name first
⏸ Pending approval Project server not approved, or folder not trusted Run claude interactively, accept trust, approve
✘ Rejected, visible only in claude mcp get A disabledMcpjsonServers entry Remove the entry from the settings file that holds it
⊘ Disabled for this project Server named in disabledMcpServers Turn it back on from the /mcp panel
! Needs authentication OAuth not completed, or refresh token rejected /mcp, then authenticate or Re-authenticate; or claude mcp login <name>
✘ Failed to connect with a 401 after adding a header Bad token, or a covered credential variable read as empty Fix the token or rename the variable; check the debug log described below
has a "url" but no "type" JSON entry without type Add "type": "http" (or sse, ws)
Warning about one name in more than one scope Different endpoints under one name Keep one; claude mcp remove <name> --scope <scope> for the rest
Warning about a missing environment variable Unset ${VAR} with no default Export the variable or add a ${VAR:-default} fallback
Warning about leading or trailing whitespace A pasted token with a trailing newline Edit the value; Claude Code uses it exactly as written
Server times out while starting Startup slower than the timeout Raise it, for example MCP_TIMEOUT=10000 claude for 10 seconds
Long tool calls abort Idle window: 5 minutes for remote servers, 30 minutes for stdio Add "timeout" in milliseconds to the entry, or set CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT
MCP server "github" disconnected · open /mcp to reconnect Five reconnect attempts with backoff failed Reconnect from /mcp; /mcp reconnect all on v2.1.284 or later
A claude.ai connector never appears An API key or other non-subscription credential is active Run /status, unset the key, then /login with your claude.ai account

For the credential row, the CLI reference documents --debug-file, which writes debug logs to a path and enables debug mode. Start with claude --debug-file /tmp/claude-debug.log and search that file for never expanded toward a remote server; that line names a covered variable your url or headers referenced.

Two rows need context. The timeout values are milliseconds, and the per-server timeout field is a hard wall-clock limit per tool call that progress notifications do not extend; values below 1000 are ignored. Separately, a remote server whose first connection fails with a transient error, such as a 5xx, a refused connection or a timeout, is already retried up to three times before Claude Code marks it failed. One manual reconnect from /mcp is therefore a better first move than editing configuration at the first red cross; reach for the configuration only when the same failure comes back with the same detail.

When many MCP tools crowd the context window

Tool search is on by default for current models. With it, only tool names and server instructions load at session start, so adding servers has “minimal impact on your context window,” and Claude Code imposes no fixed per-server tool cap; the practical limit is your context budget. That changes what “too many servers” means. The cost shows up in large tool outputs and in the few servers that load upfront, not in the raw count of servers you configured.

Work through this when sessions feel crowded:

  1. Update first. Before v2.1.306, sessions with many MCP tools could show “prompt is too long” in place of a real API error and run a compaction they did not need. If you see that message on an older build, run claude update, reproduce, and only then decide whether you have a context problem.
  2. Measure. Run /context to see what is consuming space, as Anthropic’s cost management guide suggests.
  3. Disable what you are not using. Toggle idle servers off in /mcp; the configuration stays and Claude Code stops connecting to them.
  4. Prefer a CLI when one exists. The same guide notes that tools like gh “are still more context-efficient than MCP servers because they don’t add any per-tool listing.”
  5. Bound large outputs. Claude Code warns when a tool’s output passes 10,000 tokens and limits it to 25,000 tokens by default; set MAX_MCP_OUTPUT_TOKENS, for example MAX_MCP_OUTPUT_TOKENS=50000, to change the limit. Successful text results longer than 50,000 characters are saved to a file instead of entering the conversation.
  6. Use alwaysLoad sparingly. "alwaysLoad": true on a server loads its tools upfront regardless of tool search and makes startup wait for them, capped at the standard 5-second connect timeout. Reserve it for a server Claude needs on every turn.
  7. Know the switches. ENABLE_TOOL_SEARCH=auto loads deferrable tools upfront until their definitions reach 10% of the context window, auto:5 lowers that threshold to 5%, and false loads everything upfront with no deferral.

If you route Claude Code through an LLM gateway, v2.1.305 also matters. It fixed every request failing when an endpoint or gateway rejects tool search, a 2.1.304 regression, and Claude Code now retries without it. The MCP reference adds that Claude Code tries tool search again later at the cost of another rejected request, and that setting ENABLE_TOOL_SEARCH=false skips those requests entirely.

Roll back: remove servers, reset approvals, restore .mcp.json

Rollback is cheap when each step matches the scope you used. This sequence undoes the whole worked example:

claude mcp remove db --scope local
claude mcp remove github --scope user
git diff .mcp.json
git checkout -- .mcp.json
claude mcp reset-project-choices
claude mcp logout sentry
  1. Remove each server with the scope you added it at. For remote servers, removal also deletes the OAuth tokens and client registration Claude Code stored for them.
  2. If you only want a server quiet for a while, toggle it off in /mcp instead. Claude Code records that choice per project in ~/.claude.json and keeps the definition, so turning it back on is one toggle.
  3. Restore the shared file from git. git diff .mcp.json shows what changed; git checkout -- .mcp.json returns the last committed version, and checking the file out from an earlier commit takes you further back.
  4. Reset approvals with claude mcp reset-project-choices, so the next interactive run asks again about every .mcp.json server.
  5. Clear stored OAuth credentials with claude mcp logout <name>, or choose Clear authentication in the server’s /mcp menu.
  6. If ~/.claude.json itself breaks, the settings documentation describes the recovery: Claude Code copies an unparseable file to ~/.claude/backups/.claude.json.corrupted.<timestamp> and keeps backups it saves before each write; copy back one of the five most recent .claude.json.backup.<timestamp> files in ~/.claude/backups/.

Map the same servers into Codex config.toml

If you also run OpenAI’s Codex CLI, the same two servers move into TOML. Per the Codex configuration reference, user-level configuration lives in ~/.codex/config.toml, and project-scoped overrides in .codex/config.toml load only when you trust the project. Keep the database string in the user-level file so it never sits inside a repository.

# ~/.codex/config.toml
[mcp_servers.db]
command = "npx"
args = ["-y", "@bytebase/dbhub", "--dsn", "postgresql://readonly:pass@localhost:5432/app_dev"]
startup_timeout_sec = 20

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "MY_GITHUB_MCP_PAT"
tool_timeout_sec = 60

The mapping is close, with a few differences worth knowing before you copy configuration between the two tools:

Claude Code Codex config.toml key Note
Command and arguments after -- command, args Same split between launcher and arguments
--env KEY=value env, or env_vars to pass named variables through env_vars is an allowlist of variables to forward
--transport http with a URL url Streamable HTTP endpoint
--header "Authorization: Bearer ..." bearer_token_env_var, http_headers or env_http_headers The first keeps the token out of the file
MCP_TIMEOUT startup timeout startup_timeout_sec Codex default is 10 seconds
Per-server timeout in milliseconds tool_timeout_sec Codex default is 60 seconds per tool
Toggle off in /mcp enabled = false Disables without removing
No direct equivalent required = true Fails startup or resume if the server cannot initialize
oauth.scopes scopes OAuth scopes to request when signing in

The bearer_token_env_var key gives Codex the clean version of the variable trick from Path A: the file names the variable, your shell holds the value. Our Codex startup and configuration diagnosis guide covers what to check when a Codex session starts without the servers you expect.

Sources

  1. Anthropic, Claude Code v2.1.306 release notes, GitHub, Oct 21, 2026
  2. Anthropic, Connect Claude Code to tools via MCP, Claude Code Docs
  3. Anthropic, Claude Code v2.1.305 release notes, GitHub, Oct 20, 2026
  4. Anthropic, Settings files and precedence, Claude Code Docs
  5. Anthropic, CLI reference, Claude Code Docs
  6. Anthropic, Manage costs effectively, Claude Code Docs
  7. OpenAI, Codex Configuration Reference
  8. Anthropic, Claude Code overview, Claude Code Docs
YOU'RE THROUGH THIS ONE.

Keep connecting the dots.

Back to the library