Claude Code的MCP範圍

Claude Code MCP 允許你依據用途與共享需求，將伺服器設定在不同範圍（scope）中，分為：

• Local（本地）
• Project（專案）
• User（用戶）

這三種範圍有明確的優先順序與用途，可靈活應對個人實驗、團隊共享、跨專案使用等情境。

Local Scope（本地範圍）

• 儲存位置：專案內使用者本機設定
• 權限：僅限你自己使用，不會被版本控制
• 適合：個人實驗伺服器、敏感金鑰（如 API key）、測試中的功能

claude mcp add my-private-server /path/to/server
# 或指定為 local
claude mcp add my-private-server -s local /path/to/server

Project Scope（專案範圍）

• 儲存位置：.mcp.json 檔案，放在專案根目錄
• 權限：團隊共享，可加入版本控制
• 適合：團隊共用伺服器、CI 工具、共用資料庫

claude mcp add shared-server -s project /path/to/server

.mcp.json 標準格式如下：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

出於安全考量，Claude Code 啟用 .mcp.json 內容前會要求你手動批准
（重設批准選項用：claude mcp reset-project-choices）

User Scope（用戶範圍）

• 儲存位置：用戶本機設定檔（跨專案有效）
• 權限：只有你自己能用，但所有專案都能存取
• 適合：你常用的工具伺服器、通用開發服務

claude mcp add my-user-server -s user /path/to/server

其他規則

當多個範圍定義了同名伺服器，系統會依下列順序選擇：

1. Local 本地（最高優先）
2. Project 專案
3. User 用戶（最低優先）

這表示你可以用 local 設定暫時覆蓋 project/user 設定，不怕被共享配置干擾。

可以在 .mcp.json 中使用以下格式插入環境變數：

適用位置包含：

• command：可執行檔路徑
• args：執行參數
• env：環境變數本身
• url：遠端伺服器網址
• headers：身份驗證 token 等

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

若未設 API_KEY 也沒指定 default，Claude Code 啟動時會報錯。

遠端伺服器身份驗證（OAuth 支援）

若你連接的 MCP Server 需要 OAuth 驗證，例如 GitHub API：

新增伺服器

claude mcp add --transport sse github-server https://api.github.com/mcp

使用 /mcp 指令開啟互動選單，完成登入驗證

/mcp

瀏覽器會跳出 OAuth 流程，完成授權後即可連線

• Token 會安全儲存並自動刷新
• 也可手動用 /mcp 清除驗證

PostgreSQL MCP 伺服器連線

若你想讓 Claude 幫你查詢資料庫結構，可這樣啟用：

claude mcp add postgres-server /path/to/postgres-mcp-server \
  --connection-string "postgresql://user:pass@localhost:5432/mydb"

然後直接對 Claude 下指令：

> describe the schema of our users table
> what are the most recent orders?

Claude 會進行唯讀存取，幫你檢查欄位、關聯、資料內容，非常適合熟悉新專案資料庫。