安裝 MCP servers

MCP servers 可以根據您的需求以三種不同的方式進行配置：

選項 1：新增遠端 HTTP server

HTTP servers 是連接到遠端 MCP servers 的推薦選項。這是雲端服務最廣泛支援的傳輸方式。

# 基本語法
claude mcp add --transport http <name> <url>

# 實際範例：連接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 使用 Bearer token 的範例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

當透過 .mcp.json、~/.claude.json 或 claude mcp add-json 中的 JSON 配置 MCP servers 時，type 欄位接受 streamable-http 作為 http 的別名。MCP 規範使用名稱 streamable-http 作為此傳輸，因此從 server 文件複製的配置無需修改即可運作。

選項 2：新增遠端 SSE server

# 基本語法
claude mcp add --transport sse <name> <url>

# 實際範例：連接到 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 使用驗證標頭的範例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

選項 3：新增本機 stdio server

Stdio servers 在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。

# 基本語法
claude mcp add [options] <name> -- <command> [args...]

# 實際範例：新增 Airtable server
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

管理您的 servers

配置後，您可以使用這些命令管理您的 MCP servers：

# 列出所有已配置的 servers
claude mcp list

# 取得特定 server 的詳細資訊
claude mcp get github

# 移除 server
claude mcp remove github

# (在 Claude Code 中) 檢查 server 狀態
/mcp

/mcp 面板會在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。

server 名稱 workspace 保留供內部使用。如果您的配置定義了具有該名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。

動態工具更新

Claude Code 支援 MCP list_changed 通知，允許 MCP servers 動態更新其可用工具、提示和資源，而無需您斷開連接並重新連接。當 MCP server 傳送 list_changed 通知時，Claude Code 會自動重新整理該 server 的可用功能。

自動重新連接

如果 HTTP 或 SSE server 在 session 中途斷開連接，Claude Code 會自動以指數退避方式重新連接：最多五次嘗試，從一秒延遲開始，每次加倍。在 /mcp 中，server 會顯示為待處理狀態，同時重新連接正在進行中。五次失敗嘗試後，server 被標記為失敗，您可以從 /mcp 手動重試。Stdio servers 是本機程序，不會自動重新連接。

相同的退避策略適用於 HTTP 或 SSE server 在啟動時初始連接失敗的情況。自 v2.1.121 起，Claude Code 在暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）上最多重試初始連接三次，如果仍無法連接，則將 server 標記為失敗。驗證和找不到錯誤不會重試，因為它們需要配置變更才能解決。

使用 channels 推送訊息

MCP server 也可以直接將訊息推送到您的 session 中，以便 Claude 可以回應外部事件，例如 CI 結果、監控警報或聊天訊息。若要啟用此功能，您的 server 宣告 claude/channel 功能，並在啟動時使用 --channels 旗標選擇加入。請參閱 Channels 以使用官方支援的 channel，或 Channels reference 以建立您自己的。

Plugin 提供的 MCP servers

Plugins 可以捆綁 MCP servers，在啟用 plugin 時自動提供工具和整合。Plugin MCP servers 的工作方式與使用者配置的 servers 相同。

Plugin MCP servers 的工作方式：

• Plugins 在 plugin 根目錄的 .mcp.json 中或在 plugin.json 中內聯定義 MCP servers
• 啟用 plugin 時，其 MCP servers 會自動啟動
• Plugin MCP 工具與手動配置的 MCP 工具一起出現
• Plugin servers 透過 plugin 安裝進行管理 (不是 /mcp 命令)

Plugin MCP 配置範例：

在 plugin 根目錄的 .mcp.json 中：

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

或在 plugin.json 中內聯：

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Plugin MCP 功能：

• 自動生命週期：在 session 啟動時，已啟用 plugins 的 servers 會自動連接。如果您在 session 期間啟用或停用 plugin，請執行 /reload-plugins 以連接或斷開其 MCP servers
• 環境變數：使用 ${CLAUDE_PLUGIN_ROOT} 表示 plugin 根目錄中的捆綁 plugin 檔案，以及 ${CLAUDE_PLUGIN_DATA} 表示 persistent state 在 plugin 更新後仍然存在
• 使用者環境存取：存取與手動配置的 servers 相同的環境變數
• 多種傳輸類型：支援 stdio、SSE 和 HTTP 傳輸 (傳輸支援可能因 server 而異)

檢視 plugin MCP servers：

# 在 Claude Code 中，查看所有 MCP servers，包括 plugin 的
/mcp

Plugin servers 在列表中出現，並有指示器顯示它們來自 plugins。

Plugin MCP servers 的優點：

• 捆綁分發：工具和 servers 一起打包
• 自動設定：無需手動 MCP 配置
• 團隊一致性：安裝 plugin 時，每個人都會獲得相同的工具

請參閱 plugin 元件參考，了解有關使用 plugins 捆綁 MCP servers 的詳細資訊。

MCP 安裝範圍

MCP servers 可以在三個不同的範圍級別進行配置。您選擇的範圍控制 server 在哪些專案中載入，以及配置是否與您的團隊共享。管理員也可以透過受管配置在企業級別部署 servers。

Local scope

Local scope 是預設值。本機範圍的 server 僅在您新增它的專案中載入，並對您保持私密。Claude Code 將其儲存在 ~/.claude.json 中該專案的路徑下，因此相同的 server 不會出現在您的其他專案中。使用本機範圍進行個人開發 servers、實驗配置或包含您不想在版本控制中的認證的 servers。

# 新增本機範圍的 server (預設)
claude mcp add --transport http stripe https://mcp.stripe.com

# 明確指定本機範圍
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

當您從 /path/to/your/project 執行命令時，該命令會將 server 寫入 ~/.claude.json 中您目前專案的項目。下面的範例顯示結果：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Project scope

Project scope 的 servers 透過在專案根目錄中儲存配置在 .mcp.json 檔案中來啟用團隊協作。此檔案設計為簽入版本控制，確保所有團隊成員都能存取相同的 MCP 工具和服務。新增 project scope 的 server 時，Claude Code 會自動建立或更新此檔案，使用適當的配置結構。

# 新增 project scope 的 server
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

產生的 .mcp.json 檔案遵循標準化格式：

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

出於安全考慮，Claude Code 在使用來自 .mcp.json 檔案的 project scope servers 之前會提示批准。如果您需要重設這些批准選擇，請使用 claude mcp reset-project-choices 命令。

User scope

User scope 的 servers 儲存在 ~/.claude.json 中，並提供跨專案可存取性，使其在您機器上的所有專案中可用，同時對您的使用者帳戶保持私密。此範圍非常適合個人公用程式 servers、開發工具或您在不同專案中經常使用的服務。

# 新增使用者 server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Scope 階層和優先順序

當相同的 server 在多個位置定義時，Claude Code 連接到它一次，使用來自最高優先順序來源的定義：

1. Local scope
2. Project scope
3. User scope
4. Plugin-provided servers
5. claude.ai connectors

三個範圍按名稱符合重複項。Plugins 和 connectors 按端點符合，因此指向與上述 server 相同 URL 或命令的端點被視為重複項。

.mcp.json 中的環境變數擴展

Claude Code 支援 .mcp.json 檔案中的環境變數擴展，允許團隊共享配置，同時保持機器特定路徑和 API 金鑰等敏感值的靈活性。

支援的語法：

• ${VAR} - 擴展為環境變數 VAR 的值
• ${VAR:-default} - 如果設定了 VAR，則擴展為 VAR，否則使用 default

擴展位置： 環境變數可以在以下位置擴展：

• command - server 可執行檔路徑
• args - 命令列引數
• env - 傳遞給 server 的環境變數
• url - 對於 HTTP server 類型
• headers - 對於 HTTP server 驗證

使用變數擴展的範例：

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

如果未設定必需的環境變數且沒有預設值，Claude Code 將無法解析配置。

實用範例

{/* ### 範例：使用 Playwright 自動化瀏覽器測試

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

然後編寫並執行瀏覽器測試：

Test if the login flow works with test@example.com

Take a screenshot of the checkout page on mobile

Verify that the search feature returns results
``` */}

### 範例：使用 Sentry 監控錯誤

```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

使用您的 Sentry 帳戶進行驗證：

/mcp

然後除錯生產問題：

過去 24 小時內最常見的錯誤是什麼？

顯示錯誤 ID abc123 的堆疊追蹤

哪個部署引入了這些新錯誤？

範例：連接到 GitHub 進行程式碼審查

GitHub 的遠端 MCP server 使用作為標頭傳遞的 GitHub 個人存取 token 進行驗證。若要取得一個，請開啟您的 GitHub token 設定，產生一個新的細粒度 token，具有對您希望 Claude 使用的儲存庫的存取權，然後新增 server：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

然後使用 GitHub：

審查 PR #456 並建議改進

為我們剛發現的錯誤建立新問題

顯示所有指派給我的開放 PRs

範例：查詢您的 PostgreSQL 資料庫

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

然後自然地查詢您的資料庫：

本月我們的總收入是多少？

顯示 orders 表的架構

找到 90 天內未進行購買的客戶

使用遠端 MCP servers 進行驗證

許多雲端 MCP servers 需要驗證。Claude Code 支援 OAuth 2.0 以進行安全連接。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

使用固定的 OAuth 回呼連接埠

某些 MCP servers 需要預先註冊的特定重新導向 URI。根據預設，Claude Code 為 OAuth 回呼選擇隨機可用連接埠。使用 --callback-port 固定連接埠，使其符合 http://localhost:PORT/callback 形式的預先註冊重新導向 URI。

您可以單獨使用 --callback-port (使用動態用戶端註冊) 或與 --client-id 一起使用 (使用預先配置的認證)。

# 使用動態用戶端註冊的固定回呼連接埠
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

使用預先配置的 OAuth 認證

某些 MCP servers 不支援自動 OAuth 設定。如果您看到類似「Incompatible auth server: does not support dynamic client registration」的錯誤，server 需要預先配置的認證。Claude Code 也支援使用 Client ID Metadata Document (CIMD) 而不是 Dynamic Client Registration 的 servers，並自動探索這些。如果自動探索失敗，請先透過 server 的開發人員入口網站註冊 OAuth 應用程式，然後在新增 server 時提供認證。

claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
--client-secret

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp

覆蓋 OAuth 中繼資料探索

指向 Claude Code 特定的 OAuth 授權 server 中繼資料 URL 以繞過預設探索鏈。當 MCP server 的標準端點出錯時，或當您想要透過內部代理路由探索時，設定 authServerMetadataUrl。根據預設，Claude Code 首先檢查 RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource，然後回退到 RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server。

在 .mcp.json 中 server 配置的 oauth 物件中設定 authServerMetadataUrl：

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL 必須使用 https://。authServerMetadataUrl 需要 Claude Code v2.1.64 或更新版本。中繼資料 URL 的 scopes_supported 會覆蓋上游 server 宣傳的範圍。

限制 OAuth 範圍

設定 oauth.scopes 以固定 Claude Code 在授權流程中要求的範圍。這是限制 MCP server 到安全團隊批准的子集的支援方式，當上游授權 server 宣傳的範圍超過您想要授予的範圍時。該值是單個空格分隔的字串，符合 RFC 6749 §3.3 中的 scope 參數格式。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes 優先於 authServerMetadataUrl 和 server 在 /.well-known 發現的範圍。保持未設定以讓 MCP server 決定要求的範圍集。

如果授權 server 在 scopes_supported 中宣傳 offline_access，Claude Code 會將其附加到固定範圍，以便可以在沒有新瀏覽器登入的情況下重新整理存取 token。

如果 server 稍後為工具呼叫傳回 403 insufficient_scope，Claude Code 會使用相同的固定範圍重新驗證。當您需要的工具需要固定範圍外的範圍時，擴展 oauth.scopes。

使用動態標頭進行自訂驗證

如果您的 MCP server 使用 OAuth 以外的驗證方案 (例如 Kerberos、短期 tokens 或內部 SSO)，請使用 headersHelper 在連接時產生請求標頭。Claude Code 執行命令並將其輸出合併到連接標頭中。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

命令也可以內聯：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

需求：

• 命令必須將字串鍵值對的 JSON 物件寫入 stdout
• 命令在 shell 中執行，逾時時間為 10 秒
• 動態標頭會覆蓋任何具有相同名稱的靜態 headers

helper 在每次連接時執行 (在 session 啟動和重新連接時)。沒有快取，因此您的指令碼負責任何 token 重複使用。

Claude Code 在執行 helper 時設定這些環境變數：

使用這些來編寫為多個 MCP servers 服務的單一 helper 指令碼。

從 JSON 配置新增 MCP servers

如果您有 MCP server 的 JSON 配置，您可以直接新增它：

# 基本語法
claude mcp add-json <name> '<json>'

# 範例：使用 JSON 配置新增 HTTP server
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 範例：使用 JSON 配置新增 stdio server
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# 範例：使用預先配置的 OAuth 認證新增 HTTP server
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

claude mcp get weather-api

從 Claude Desktop 匯入 MCP servers

如果您已在 Claude Desktop 中配置了 MCP servers，您可以匯入它們：

# 基本語法 
claude mcp add-from-claude-desktop 

claude mcp list 

使用來自 Claude.ai 的 MCP servers

如果您已使用 Claude.ai 帳戶登入 Claude Code，您在 Claude.ai 中新增的 MCP servers 會自動在 Claude Code 中可用：

/mcp

您在 Claude Code 中新增的 server 優先於指向相同 URL 的 claude.ai connector。發生這種情況時，/mcp 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。

若要在 Claude Code 中停用 claude.ai MCP servers，請將 ENABLE_CLAUDEAI_MCP_SERVERS 環境變數設定為 false：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

使用 Claude Code 作為 MCP server

您可以使用 Claude Code 本身作為其他應用程式可以連接到的 MCP server：

# 啟動 Claude 作為 stdio MCP server
claude mcp serve

您可以透過將此配置新增到 claude_desktop_config.json 在 Claude Desktop 中使用它：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

MCP 輸出限制和警告

當 MCP 工具產生大型輸出時，Claude Code 可幫助管理 token 使用情況，以防止淹沒您的對話內容：

• 輸出警告閾值：當任何 MCP 工具輸出超過 10,000 個 tokens 時，Claude Code 會顯示警告
• 可配置限制：您可以使用 MAX_MCP_OUTPUT_TOKENS 環境變數調整最大允許的 MCP 輸出 tokens
• 預設限制：預設最大值為 25,000 個 tokens
• 範圍：環境變數適用於未宣告自己限制的工具。設定 anthropic/maxResultSizeChars 的工具使用該值代替文字內容，無論 MAX_MCP_OUTPUT_TOKENS 設定為什麼。傳回影像資料的工具仍受 MAX_MCP_OUTPUT_TOKENS 限制

若要增加產生大型輸出的工具的限制：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

這在使用以下 MCP servers 時特別有用：

• 查詢大型資料集或資料庫
• 產生詳細報告或文件
• 處理廣泛的日誌檔案或除錯資訊

提高特定工具的限制

如果您正在建立 MCP server，您可以透過在工具的 tools/list 回應項目中設定 _meta["anthropic/maxResultSizeChars"] 來允許個別工具傳回超過預設持久化到磁碟閾值的結果。Claude Code 將該工具的閾值提高到註解值，最高為 500,000 個字元的硬上限。

這對於傳回本質上很大但必要的輸出的工具很有用，例如資料庫架構或完整檔案樹。沒有註解，超過預設閾值的結果會持久化到磁碟，並在對話中被檔案參考取代。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

對於文字內容，註解獨立於 MAX_MCP_OUTPUT_TOKENS 應用，因此使用者無需提高環境變數來使用宣告它的工具。傳回影像資料的工具仍受 token 限制。

回應 MCP 引發請求

MCP servers 可以使用引發在任務中途要求您提供結構化輸入。當 server 需要無法自行取得的資訊時，Claude Code 會顯示互動式對話框並將您的回應傳回給 server。您無需進行任何配置：當 server 要求時，引發對話框會自動出現。

Servers 可以透過兩種方式要求輸入：

• 表單模式：Claude Code 顯示一個對話框，其中包含 server 定義的表單欄位 (例如，使用者名稱和密碼提示)。填入欄位並提交。
• URL 模式：Claude Code 開啟瀏覽器 URL 以進行驗證或批准。在瀏覽器中完成流程，然後在 CLI 中確認。

若要自動回應引發請求而不顯示對話框，請使用 Elicitation hook。

如果您正在建立使用引發的 MCP server，請參閱 MCP 引發規格，了解協議詳細資訊和架構範例。

使用 MCP 資源

MCP servers 可以公開資源，您可以使用 @ 提及來參考，類似於您參考檔案的方式。

參考 MCP 資源

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Compare @postgres:schema://users with @docs:file://database/user-model

使用 MCP Tool Search 進行擴展

Tool search 透過延遲工具定義直到 Claude 需要它們來保持 MCP 內容使用低。只有工具名稱在 session 啟動時載入，因此新增更多 MCP servers 對您的內容視窗的影響最小。

工作原理

Tool search 預設啟用。MCP 工具被延遲而不是預先載入到內容中，Claude 使用搜尋工具在任務需要時探索相關的工具。只有 Claude 實際使用的工具才會進入內容。從您的角度來看，MCP 工具的工作方式完全相同。

如果您偏好基於閾值的載入，請設定 ENABLE_TOOL_SEARCH=auto 以在工具適合內容視窗的 10% 內時預先載入架構，並僅延遲溢出。請參閱 配置 tool search 了解所有選項。

對於 MCP server 作者

如果您正在建立 MCP server，啟用 Tool Search 時 server 指示欄位會變得更有用。Server 指示可幫助 Claude 了解何時搜尋您的工具，類似於 skills 的工作方式。

新增清晰、描述性的 server 指示，說明：

• 您的工具處理的任務類別
• Claude 應何時搜尋您的工具
• 您的 server 提供的關鍵功能

Claude Code 將工具描述和 server 指示截斷為每個 2KB。保持簡潔以避免截斷，並將關鍵詳細資訊放在開始處。

配置 tool search

Tool search 預設啟用：MCP 工具被延遲並按需探索。當 ANTHROPIC_BASE_URL 指向非第一方主機時，tool search 預設停用，因為大多數代理不轉發 tool_reference 區塊。設定 ENABLE_TOOL_SEARCH 明確選擇加入。此功能需要支援 tool_reference 區塊的模型：Sonnet 4 及更新版本，或 Opus 4 及更新版本。Haiku 模型不支援 tool search。

使用 ENABLE_TOOL_SEARCH 環境變數控制 tool search 行為：

# 使用自訂 5% 閾值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全停用 tool search
ENABLE_TOOL_SEARCH=false claude

或在您的 settings.json env 欄位 中設定值。

您也可以特別停用 ToolSearch 工具：

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

豁免伺服器延遲

如果伺服器的工具應始終對 Claude 可見而無需搜尋步驟，請在該伺服器的配置中將 alwaysLoad 設定為 true。該伺服器的每個工具隨後都會在 session 啟動時載入到內容中，無論 ENABLE_TOOL_SEARCH 設定如何。對於 Claude 在每個回合都需要的少量工具，請使用此選項，因為每個預先載入的工具會消耗內容，否則這些內容將可用於您的對話。

以下 .mcp.json 項目豁免一個 HTTP 伺服器，同時保持其他伺服器延遲：

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 _meta 物件中包含 "anthropic/alwaysLoad": true 來標記個別工具為始終載入，這對該工具只有相同的效果。

設定 alwaysLoad: true 也會阻止啟動直到伺服器連線，上限為標準 5 秒連線逾時。即使設定了 MCP_CONNECTION_NONBLOCKING=1，這也適用，因為工具必須在建立第一個提示時存在。當啟用非阻塞時，其他伺服器仍在背景中連線。

使用 MCP 提示作為命令

MCP servers 可以公開提示，這些提示在 Claude Code 中變成可用的命令。

執行 MCP 提示

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

受管理的 MCP 配置

對於需要對 MCP servers 進行集中控制的組織，Claude Code 支援兩個配置選項：

1. 使用 managed-mcp.json 的獨佔控制：部署一組固定的 MCP servers，使用者無法修改或擴展
2. 使用允許清單/拒絕清單的基於原則的控制：允許使用者新增自己的 servers，但限制允許的 servers

這些選項允許 IT 管理員：

• 控制員工可以存取的 MCP servers：在整個組織中部署一組標準化的已批准 MCP servers
• 防止未授權的 MCP servers：限制使用者新增未批准的 MCP servers
• 完全停用 MCP：如果需要，完全移除 MCP 功能

選項 1：使用 managed-mcp.json 的獨佔控制

當您部署 managed-mcp.json 檔案時，它對所有 MCP servers 進行獨佔控制。使用者無法新增、修改或使用此檔案中定義的 MCP servers 以外的任何 MCP servers。這是希望完全控制的組織的最簡單方法。

系統管理員將配置檔案部署到系統範圍的目錄：

• macOS：/Library/Application Support/ClaudeCode/managed-mcp.json
• Linux 和 WSL：/etc/claude-code/managed-mcp.json
• Windows：C:\Program Files\ClaudeCode\managed-mcp.json

managed-mcp.json 檔案使用與標準 .mcp.json 檔案相同的格式：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

選項 2：使用允許清單和拒絕清單的基於原則的控制

管理員可以允許使用者配置自己的 MCP servers，同時對允許的 servers 強制執行限制，而不是進行獨佔控制。此方法在 受管理設定檔案 中使用 allowedMcpServers 和 deniedMcpServers。

限制選項

允許清單或拒絕清單中的每個項目可以透過三種方式限制 servers：

1. 按 server 名稱 (serverName)：符合 server 的已配置名稱
2. 按命令 (serverCommand)：符合用於啟動 stdio servers 的確切命令和引數
3. 按 URL 模式 (serverUrl)：符合遠端 server URLs，支援萬用字元

重要：每個項目必須恰好有 serverName、serverCommand 或 serverUrl 之一。

配置範例

{
  "allowedMcpServers": [
    // 按 server 名稱允許
    { "serverName": "github" },
    { "serverName": "sentry" },

    // 按確切命令允許 (對於 stdio servers)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // 按 URL 模式允許 (對於遠端 servers)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // 按 server 名稱阻止
    { "serverName": "dangerous-server" },

    // 按確切命令阻止 (對於 stdio servers)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // 按 URL 模式阻止 (對於遠端 servers)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

基於命令的限制如何工作

確切符合：

• 命令陣列必須確切符合 - 命令和所有引數的順序正確
• 範例：["npx", "-y", "server"] 將不符合 ["npx", "server"] 或 ["npx", "-y", "server", "--flag"]

Stdio server 行為：

• 當允許清單包含任何 serverCommand 項目時，stdio servers 必須符合其中一個命令
• Stdio servers 在存在命令限制時無法單獨按名稱通過
• 這確保管理員可以強制執行允許執行的命令

非 stdio server 行為：

• 遠端 servers (HTTP、SSE、WebSocket) 在允許清單中存在 serverUrl 項目時使用基於 URL 的符合
• 如果不存在 URL 項目，遠端 servers 會回退到基於名稱的符合
• 命令限制不適用於遠端 servers

基於 URL 的限制如何工作

URL 模式使用 * 支援萬用字元以符合任何字元序列。這對於允許整個網域或子網域很有用。

萬用字元範例：

• https://mcp.company.com/* - 允許特定網域上的所有路徑
• https://*.example.com/* - 允許 example.com 的任何子網域
• http://localhost:*/* - 允許 localhost 上的任何連接埠

主機名稱符合不區分大小寫，並忽略尾部 FQDN 點，符合 DNS 語義。像 *://Mcp.Example.com/* 這樣的模式符合 https://mcp.example.com/api，而 https://mcp.example.com. 的處理方式與 https://mcp.example.com 相同。配置和路徑保持區分大小寫。

遠端 server 行為：

• 當允許清單包含任何 serverUrl 項目時，遠端 servers 必須符合其中一個 URL 模式
• 遠端 servers 在存在 URL 限制時無法單獨按名稱通過
• 這確保管理員可以強制執行允許的遠端端點

{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.company.com/*" },
{ "serverUrl": "https://*.internal.corp/*" }
]
}

{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

允許清單行為 (allowedMcpServers)

• undefined (預設)：無限制 - 使用者可以配置任何 MCP server
• 空陣列 []：完全鎖定 - 使用者無法配置任何 MCP servers
• 項目清單：使用者只能配置符合名稱、命令或 URL 模式的 servers

拒絕清單行為 (deniedMcpServers)

• undefined (預設)：沒有 servers 被阻止
• 空陣列 []：沒有 servers 被阻止
• 項目清單：指定的 servers 在所有範圍中被明確阻止

重要注意事項

• 選項 1 和選項 2 可以結合：如果 managed-mcp.json 存在，它具有獨佔控制，使用者無法新增 servers。允許清單/拒絕清單仍然適用於受管理的 servers 本身。
• 拒絕清單具有絕對優先順序：如果 server 符合拒絕清單項目 (按名稱、命令或 URL)，即使它在允許清單上也會被阻止
• 基於名稱、基於命令和基於 URL 的限制一起工作：如果 server 符合任何名稱項目、命令項目或 URL 模式，它就會通過 (除非被拒絕清單阻止)