Project-Scoped MCP Servers vs Global Config

Project-scoped MCP servers, configured with claude mcp add --scope project, reduce token waste by limiting which tools the model sees to what the current project actually needs. Global MCP config loads every server into every conversation, burning context tokens on tools the model will never call. Project scoping fixes this.

Global config: the default problem

When you add an MCP server globally, every Claude Code session loads its tool definitions into the context window. A search MCP with 5 tools, a database MCP with 8 tools, a filesystem MCP with 12 tools -- that is 25 tool schemas consuming context tokens before you type a single prompt. Each tool schema runs 200-500 tokens for the description, parameters, and examples. At 25 tools, you lose 5K-12K tokens of context to tool definitions alone.

# Global config: every project sees these servers
claude mcp add --scope global search-api -- npx @scavio/mcp-server
claude mcp add --scope global postgres -- npx @modelcontextprotocol/server-postgres
claude mcp add --scope global github -- npx @modelcontextprotocol/server-github

# Now EVERY project loads all three servers.
# A frontend project does not need postgres tools.
# A data pipeline does not need github tools.

Project scoping: load what you need

# In your web scraping project:
cd ~/projects/market-research
claude mcp add --scope project search-api -- npx @scavio/mcp-server

# In your database project:
cd ~/projects/analytics-pipeline
claude mcp add --scope project postgres -- npx @modelcontextprotocol/server-postgres
claude mcp add --scope project search-api -- npx @scavio/mcp-server

# In your frontend project:
cd ~/projects/landing-page
claude mcp add --scope project github -- npx @modelcontextprotocol/server-github
# No search or postgres tools loaded -- fewer tokens wasted

Where the config lives

Global config goes in ~/.claude/settings.json under the mcpServers key. Project config goes in .claude/settings.json inside your project directory. The project file is committed to version control, so your entire team gets the same MCP setup.

// .claude/settings.json (project-scoped)
{
  "mcpServers": {
    "search-api": {
      "command": "npx",
      "args": ["@scavio/mcp-server"],
      "env": {
        "SCAVIO_API_KEY": "your-key-here"
      }
    }
  }
}

When global config makes sense

Some MCP servers belong in global config because they are universally useful. Filesystem access is a reasonable global server -- nearly every project needs to read and write files. Memory/knowledge-base servers that maintain context across projects also belong globally.

The rule of thumb: if you use it in more than 80% of projects, make it global. Everything else should be project-scoped.

Search MCP benefits from project scoping

A search MCP like Scavio is a good candidate for project scoping. Market research projects need it. Data enrichment pipelines need it. But your infrastructure automation project and your UI component library do not. Project scoping keeps the search tools available where they add value and invisible where they add noise.

# Add Scavio MCP to a research project
cd ~/projects/competitor-analysis
claude mcp add --scope project scavio -- npx @scavio/mcp-server

# Or use the hosted MCP endpoint directly in config
# .claude/settings.json
# {
#   "mcpServers": {
#     "scavio": {
#       "type": "url",
#       "url": "https://mcp.scavio.dev/mcp"
#     }
#   }
# }

Token savings calculation

# Rough token impact of unnecessary MCP tools in context

tools_per_server = {
    "search-api": 5,
    "postgres": 8,
    "github": 12,
    "filesystem": 6,
    "memory": 4,
}

tokens_per_tool = 350  # average schema size

# Global config: all servers loaded
global_tokens = sum(tools_per_server.values()) * tokens_per_tool
print(f"Global config: {global_tokens:,} tokens for tool schemas")

# Project-scoped: only search for a research project
project_tokens = tools_per_server["search-api"] * tokens_per_tool
print(f"Project scoped: {project_tokens:,} tokens for tool schemas")

saved = global_tokens - project_tokens
print(f"Saved: {saved:,} tokens per conversation turn")
print(f"Over 50 turns: {saved * 50:,} tokens saved")

# At Claude's context pricing, this adds up across teams

Team workflow with project-scoped MCP

When .claude/settings.json is committed to your repo, every team member who clones the project gets the same MCP servers configured automatically. No setup docs needed, no "make sure you add the search MCP" messages. The project knows what it needs.

For API keys, use environment variables referenced in the config rather than hardcoded values. Each developer sets their own keys locally, but the server configuration is shared.

// .claude/settings.json -- committed to repo
{
  "mcpServers": {
    "scavio": {
      "command": "npx",
      "args": ["@scavio/mcp-server"],
      "env": {
        "SCAVIO_API_KEY": ""
      }
    }
  }
}

// Developer sets in their shell profile:
// export SCAVIO_API_KEY="sk-live-..."
// The MCP server picks it up from the environment

Project-scoped MCP is a small configuration change that compounds across every conversation. Fewer unnecessary tools means the model spends less time parsing irrelevant schemas and more time on your actual task. For teams running dozens of Claude Code sessions daily, the token savings and improved tool selection accuracy are worth the five minutes of setup.