Scoping

Scoping determines how MCP server processes are shared across terminals and workspaces. The right scope balances resource efficiency with proper isolation.

Scope Types

Scope	Sharing	Use Case
global	All terminals, all workspaces	Stateless tools (docs, filesystem)
workspace	Terminals in same project	Project-specific credentials
credential	Terminals with same env vars	Multi-account scenarios

Global Scope

A single server instance is shared by all terminals across all workspaces. This is the most memory-efficient option.

{
  "context7": {
    "command": "npx",
    "args": ["-y", "@context7/mcp-server"],
    "scope": "global"
  }
}

Best for:

• Documentation servers — Context7, ReadTheDocs
• Filesystem servers — Local file access
• Stateless tools — Web search, calculators

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Workspace A │ │ Workspace A │ │ Workspace B │
│ Terminal 1  │ │ Terminal 2  │ │ Terminal 3  │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
       │               │               │
       └───────────────┼───────────────┘
                       │
                ┌──────▼──────┐
                │  Context7   │  ← Single instance
                │  (global)   │     serves all
                └─────────────┘

Workspace Scope

One server instance per workspace (project directory). Terminals in the same workspace share a process, but different workspaces get separate instances.

{
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server"],
    "env": {
      "SUPABASE_URL": "${SUPABASE_URL}",
      "SUPABASE_KEY": "${SUPABASE_KEY}"
    },
    "scope": "workspace"
  }
}

Best for:

• Database servers — Supabase, Postgres, Firebase
• Project APIs — Servers using project-specific .env
• State isolation — When server maintains project state

┌─────────────┐ ┌─────────────┐    ┌─────────────┐
│ Workspace A │ │ Workspace A │    │ Workspace B │
│ Terminal 1  │ │ Terminal 2  │    │ Terminal 3  │
└──────┬──────┘ └──────┬──────┘    └──────┬──────┘
       │               │                  │
       └───────┬───────┘                  │
               │                          │
        ┌──────▼──────┐            ┌──────▼──────┐
        │  Supabase   │            │  Supabase   │
        │  (WS-A)     │            │  (WS-B)     │
        │  PROD creds │            │  DEV creds  │
        └─────────────┘            └─────────────┘

Credential Scope

One server instance per unique set of credentials. Useful when you work with multiple accounts of the same service.

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    },
    "scope": "credential"
  }
}

Best for:

• Multi-account access — Personal vs work GitHub
• Client projects — Different API keys per client
• Environment separation — Prod vs staging credentials

Workspace A (.env: GITHUB_TOKEN=personal_token)
├── Terminal 1 ─┬─→ GitHub (personal_token)
├── Terminal 2 ─┘

Workspace B (.env: GITHUB_TOKEN=work_token)
├── Terminal 3 ─┬─→ GitHub (work_token)
├── Terminal 4 ─┘

Workspace C (.env: GITHUB_TOKEN=personal_token)
├── Terminal 5 ─────→ GitHub (personal_token)  ← Reuses WS-A instance!

tip

Credential scope hashes the env values to determine sharing. Two workspaces with identical credentials share a single instance.

Choosing the Right Scope

Is the server stateless?
├─ YES → Use global scope
└─ NO
   └─ Does it need per-project credentials?
      ├─ YES → Do you have multiple accounts?
      │   ├─ YES → Use credential scope
      │   └─ NO → Use workspace scope
      └─ NO → Use global scope

Memory Impact

Example with 3 workspaces, 2 terminals each (6 total):

Scope	Instances	Memory (50MB/server)
global	1	50 MB
workspace	3	150 MB
credential	1-3 (depends on env)	50-150 MB
Traditional (no gateway)	6	300 MB

Mixed Scoping

Use different scopes for different servers based on their requirements:

{
  "mcpServers": {
    "context7": {
      "scope": "global",
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    },
    "filesystem": {
      "scope": "global",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "supabase": {
      "scope": "workspace",
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_KEY": "${SUPABASE_KEY}"
      }
    },
    "github": {
      "scope": "credential",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}