Set up MCP servers once for every project

Run claude mcp add --scope user <name> … and the server loads in every project on that computer. Without the flag, Claude Code uses local scope, which means this project only. A .mcp.json file in the repo is project scope, shared with everyone who clones it. Codex keeps its own, separate list in ~/.codex/config.toml.

For one agent on one computer, --scope user is all you need. Two agents, a second laptop or a work Notion that must stay out of a side project each need more than that.

The command#

From Anthropic's MCP docs, adding a remote server for all your projects looks like this:

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

The same command with --scope local (the default) or --scope project puts the server somewhere else. If the server needs a sign-in, open Claude Code, run /mcp and finish the steps in your browser. claude mcp login <name> runs the same sign-in from your shell. Claude Code stores the token and refreshes it for you.

The three Claude Code scopes#

Define github in two scopes and Claude Code still connects to it once, using the definition highest in this order: local, then project, then user, then plugin servers, then claude.ai connectors. It takes that whole entry and doesn't merge fields across scopes. A local github you made for one repo therefore silently replaces your user-scope github in that repo, which is useful for an override and confusing once you've forgotten it exists.

.mcp.json vs ~/.claude.json#

• ~/.claude.json is yours. It holds both your user-scope servers and your local ones (filed under each project's path). It never goes into a repo.
• .mcp.json belongs to the project. It sits in the repo root and is meant to be committed, so everyone on the team gets the same servers. Claude Code asks for approval the first time it meets a project's servers in an interactive session. To forget those choices, run claude mcp reset-project-choices.
• Keep secrets out of .mcp.json. It supports ${VAR} and ${VAR:-default} in command, args, env, url and headers, so the file can name the variable and each person keeps the value in their own environment:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Check what's actually loaded#

Three commands show which definition won and what it costs in context.

• claude mcp list shows every server Claude Code knows about. If a ${VAR} in .mcp.json isn't set, it reports a missing-variable warning for that server here instead of failing quietly.
• /mcp inside a session shows which servers connected, lets you sign in or out, and lets you turn off the ones you don't need right now.
• /context shows what is taking up the context window.

Anthropic's cost docs note that MCP tool definitions are deferred by default, so only tool names and server instructions sit in context until Claude uses a tool. Fewer servers per project still means less for the agent to read and fewer wrong tools to reach for, which is a good reason not to put everything in user scope.

Then there's Codex#

Codex has its own MCP list, in its own format. Per OpenAI's docs, servers live in ~/.codex/config.toml, one [mcp_servers.<server-name>] table each. A project can have its own .codex/config.toml, but Codex only reads it for trusted projects. You add servers with codex mcp add, for example:

codex mcp add context7 -- npx -y @upstash/context7-mcp

and sign in with codex mcp login <server-name>.

Why keeping both in step gets tedious#

No single step is hard. The count is what grows:

• JSON for Claude Code, TOML for Codex, so copying a server across means translating it.
• Each agent runs its own sign-in to the server and keeps its own token.
• Both lists live in your home folder, so a second laptop or a server starts empty.
• The lists drift. Add Sentry to Claude Code on Tuesday, forget Codex, and on Thursday Codex can't see the error you're asking it to fix.

One server used by two agents on two computers means four entries to add and four sign-ins to approve. Ten servers mean forty of each.

Different credentials per project#

Take a work Notion and a personal Notion. A server name can only point at one sign-in, so by hand you make two servers:

1. Add notion-work with local scope inside your work projects.
2. Add notion-personal with local scope inside your own projects.
3. Run /mcp in one project of each kind and sign each one in to the right workspace.

A server that takes a token instead of a browser sign-in can stay one entry. .mcp.json names ${API_KEY}, the file is the same in every clone, and each project gets its own value from the environment Claude Code starts in. Codex needs the same split in its own config.

User and local servers live in your home folder, not in the repo, so a new machine means running each claude mcp add and codex mcp add again from memory.

How Shuriken does it#

Shuriken's Global MCPs replace the per-agent, per-computer lists with one.

• Settings › Extensions › MCP servers shows every server once. Pick one of 57 ready-made connectors (GitHub, Linear, Notion, Slack, Sentry, Supabase, Playwright, Context7 and more) or add any server by address or command.
• Each server runs in All projects or in the projects you tick. Change it any time from the server's row.
• The sign-in belongs to the server, not to your AI account. When Shuriken moves a chat to another of your accounts at a limit, or you open another project, nobody asks you to sign in again.
• Add Notion twice, sign each one in to its own workspace, and give each its own projects. The steps for that setup are in Two Notion workspaces, one MCP list.
• Sign-ins travel between your computers and servers end-to-end encrypted. Our cloud sees a hash and a sealed box, never the token.
• A server on All projects goes into Claude Code's user config on each computer. A server for chosen projects goes where claude mcp add puts one by default: that project's section of Claude Code's config, outside the project folder, so Shuriken adds no file to your repo. Codex, Gemini CLI and the other agents get the project's servers handed to them when a chat starts.

There is one exception. Servers you added straight into Codex's own config.toml have no per-project on/off switch in Codex, so every Codex chat in every project gets them, and turning one off turns it off everywhere. Shuriken's list says so on that row.

Global MCPs are on every plan, Free included. Our picks, grouped by job from code and errors to payments, are in Best MCP servers for Claude Code. To skip the copy-pasting, download Shuriken and open Settings › Extensions › MCP servers.