Scope MCP Servers Globally or Per-Project
Not every MCP server belongs in every project. Claude Code lets you configure servers at user scope — available everywhere — or project scope — only for that specific repo.
~/.claude/settings.json ← global: available in every project
.claude/settings.json ← project: only available in this repo
A typical split:
// ~/.claude/settings.json — tools you always want
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": { "BRAVE_API_KEY": "..." }
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
}
}
}
// .claude/settings.json — tools specific to this repo
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": { "DATABASE_URL": "postgresql://localhost/myapp_dev" }
}
}
}
Both configs are merged at runtime — project settings take precedence on conflicts. This means you can override a global server with a project-specific version if needed.
Global scope is ideal for utilities like web search, note-taking, or a shared filesystem tool. Project scope is right for database connections, internal APIs, or any server that requires project-specific credentials.
Scope your MCP servers like environment variables: global for utilities, local for project-specific secrets.
Log in to leave a comment.
MCP servers aren't just for third-party integrations — you can build your own to give Claude direct access to your internal tools, databases, APIs, and workflows. A custom MCP server turns any system your team uses into a tool Claude can call natively from your session.
MCP servers can be scoped at three levels — user (available everywhere you work), project (shared with the team via version control), or enterprise (managed by your organization). Pick the right scope so each project gets exactly the tools it needs without cluttering unrelated ones.
Instead of manually editing settings JSON to add MCP servers, use the claude mcp command — add servers with one line, list what's configured, remove ones you don't need, and scope them to the right level, all from the terminal.