MCP Servers: Global vs Project Scope Across All Platforms

Every time you add an MCP server or a skill, you choose where it lives. Get it wrong and you end up with personal credentials in a git repo, or a useful tool missing from half your projects. This page gives a simple rule, then the exact locations for each platform.

The Decision Logic

Is this a personal tool I want everywhere? (notes, search)
  → Global config

Does it use credentials that are mine, not the project's?
  → Global config (never commit personal secrets)

Should everyone on the team have this automatically?
  → Project config (commit to git)

Is this tool specific to this project's infrastructure?
  → Project config

Not sure?
  → Start global. Move to project when you share it.

Config Locations: Every Platform

Claude Desktop

Global only — no project-level concept.

Claude Code

On Windows, ~ is %USERPROFILE%. When the same name is in more than one scope, Claude Code uses local, then project, then user.

Cursor

OpenClaw

OpenClaw skills are SKILL.md folders, not MCP config. Its "project" level is the agent workspace.

# One agent: installs into the workspace's skills/ folder (run from the workspace)
npx skills add <owner>/<repo> --skill <name> -a openclaw
openclaw skills install @owner/<slug>

# All local agents: installs into ~/.openclaw/skills/
npx skills add <owner>/<repo> --skill <name> -a openclaw -g
openclaw skills install @owner/<slug> --global

Workspace skills win over shared skills when two have the same name.

Team Workflow for Claude Code

1. Each developer adds personal tools with claude mcp add --scope user
2. Add team tools with claude mcp add --scope project, with no personal credentials
3. Commit .mcp.json to git
4. Use ${VAR_NAME} references for anything that varies per developer
5. List the environment variables each developer must set in your README

.mcp.json (safe to commit):

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
    }
  }
}

Each developer's shell (NOT committed):

export BRAVE_API_KEY=your-own-key
claude

Claude Code reads the value from the environment it starts in. It does not load a .env file for you.

Frequently Asked Questions

Can the same MCP server be in both user and project config?

Yes. In Claude Code, the project entry wins over the user entry, and a local entry wins over both. This lets a project use a different database connection from your personal setup.

How do I share MCP servers with my team?

Add them to the project's config file and commit it. In Claude Code that file is .mcp.json. Each developer approves the servers the first time Claude Code sees them.

What's the safest way to handle API keys in project config?

Use ${VAR_NAME} references. Each developer sets the real value in their own environment. The committed file holds no secrets.

Does Claude Desktop support project-level config?

No — it's global only. For project-level MCP config, use Claude Code or Cursor.