wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-06-09 23:15:17

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/extensibility/mcp-configuration.md
+71 -128
View File
@@ -1,14 +1,21 @@
---
title: "MCP 配置 - 多来源合并、作用域与策略管控"
description: "详细说明 Claude Code MCP 配置的来源层次、合并优先级、传输类型、企业策略管控、插件集成和保留名称机制。"
keywords: ["MCP", "配置", "settings.json", ".mcp.json", "企业策略", "插件"]
tags: [MCP, 配置, settings-json, 企业策略, 插件, Claude-Code]
create time: 2026-06-09 22:30
---
## 配置来源与作用域
# MCP 配置 - 多来源合并、作用域与策略管控
## 概述
Claude Code 的 MCP 配置来自 8 个来源（企业管控、项目、用户、插件、claude.ai 等），按优先级合并，支持 stdio/SSE/HTTP/WebSocket 四种传输类型。企业管控可进入排他模式覆盖所有其他配置，并通过 allowlist/denylist 策略精细控制可用服务器。
## 正文
### 配置来源与作用域
Claude Code 的 MCP 配置来自多个来源，每个来源对应一个 `scope`（作用域）。配置按优先级合并，高优先级来源的同名配置覆盖低优先级。
### 来源列表
#### 来源列表
| 来源 | Scope | 文件/接口 | 说明 |
|------|-------|----------|------|
@@ -21,27 +28,22 @@ Claude Code 的 MCP 配置来自多个来源，每个来源对应一个 `scope`
| 内置动态 | `dynamic` | 代码中注册 | Computer Use / Chrome 等内置服务器 |
| IDE SDK | `sdk` | IDE 传入 | VS Code / JetBrains 嵌入模式 |
### 合并优先级（从低到高）
#### 合并优先级（从低到高）
```
claude.ai 连接器 ← 最低优先级
↓ 去重
插件服务器
↓ 去重
用户全局配置
↓
项目配置（.mcp.json） ← 需要用户审批
↓
本地项目配置
↓
动态配置（内置 MCP） ← 最高优先级
```mermaid
flowchart TD
A["claude.ai 连接器\n最低优先级"] --> B["插件服务器"]
B --> C["用户全局配置"]
C --> D["项目配置 .mcp.json\n需要用户审批"]
D --> E["本地项目配置"]
E --> F["动态配置 内置 MCP\n最高优先级"]
```
`Object.assign({}, dedupedPluginServers, userServers, approvedProjectServers, localServers)` 实现合并——后出现的同名键覆盖前者。
## 企业管控模式
### 企业管控模式
当 `managed-mcp.json` 文件存在时，进入 **排他模式**：
当 `managed-mcp.json` 文件存在时，进入**排他模式**：
```typescript
// config.ts:1084
@@ -51,15 +53,15 @@ if (doesEnterpriseMcpConfigExist()) {
}
```
特性：
- 路径由系统管理决定（`getManagedFilePath()` + `managed-mcp.json`）
- 覆盖所有用户级、项目级、插件和 claude.ai 配置
- 仍然应用策略过滤（allowlist/denylist）
- 无法通过 CLI 添加新服务器（`addMcpConfig` 会拒绝）
> [!warning] 排他模式特性
> - 路径由系统管理决定
> - 覆盖所有用户级、项目级、插件和 claude.ai 配置
> - 仍然应用策略过滤（allowlist/denylist）
> - 无法通过 CLI 添加新服务器
## 传输类型与配置 Schema
### 传输类型与配置 Schema
### stdio（默认）
#### stdio（默认）
启动子进程，通过 stdin/stdout JSON-RPC 通信。
@@ -75,11 +77,12 @@ if (doesEnterpriseMcpConfigExist()) {
`type` 字段可省略（默认为 `stdio`）。环境变量通过 `env` 传递给子进程，会与当前进程环境合并。
**Windows 注意**：使用 `npx` 需要包装为 `cmd /c npx`，否则会报错。
> [!tip] Windows 注意
> 使用 `npx` 需要包装为 `cmd /c npx`，否则会报错。
### SSE（Server-Sent Events）
#### SSE（Server-Sent Events）
通过 HTTP SSE 连接远程 MCP 服务器。
通过 HTTP SSE 连接远程 MCP 服务器，支持 OAuth 认证流程。
```json
{
@@ -95,11 +98,9 @@ if (doesEnterpriseMcpConfigExist()) {
}
```
支持 OAuth 认证流程。认证失败时进入 `needs-auth` 状态，15 分钟 TTL 缓存避免重复提示。
认证失败时进入 `needs-auth` 状态，15 分钟 TTL 缓存避免重复提示。
### HTTP（Streamable HTTP）
HTTP 流式传输。
#### HTTP（Streamable HTTP）
```json
{
@@ -113,7 +114,7 @@ HTTP 流式传输。
支持与 SSE 相同的 OAuth 配置。
### WebSocket
#### WebSocket
```json
{
@@ -124,26 +125,18 @@ HTTP 流式传输。
}
```
### IDE 专用类型（内部）
#### 内部传输类型
`sse-ide` 和 `ws-ide` 是 IDE 扩展专用类型，不由用户直接配置。
| 类型 | 用途 | 认证方式 |
|------|------|---------|
| `sse-ide` | IDE 扩展专用 | lockfile token |
| `ws-ide` | IDE WebSocket | `X-Claude-Code-Ide-Authorization` header |
| `sdk` | IDE 嵌入模式 | 不经过保留名称检查和企业管控 |
| `claudeai-proxy` | claude.ai 连接器 | OAuth bearer + 401 重试 |
- `sse-ide`：使用 lockfile token 认证
- `ws-ide`：使用 `X-Claude-Code-Ide-Authorization` header
### 配置操作
### SDK 类型（内部）
`type: "sdk"` 由 IDE 嵌入模式传入，不经过保留名称检查和企业管控排他限制。
### claude.ai 代理类型（内部）
`type: "claudeai-proxy"` 由 claude.ai 网页端配置的连接器使用，通过 OAuth bearer token 认证并支持 401 重试。
## 配置操作
### 添加 MCP 服务器
通过 CLI 命令 `claude mcp add` 或 API 调用 `addMcpConfig()`：
#### 添加 MCP 服务器
```bash
# 添加到用户配置
@@ -164,19 +157,14 @@ claude mcp add my-remote -s user -t http -u https://mcp.example.com/mcp
4. **Schema 验证**：Zod 校验配置格式
5. **策略检查**：denylist 拒绝、allowlist 验证
### 移除 MCP 服务器
#### 移除和列出
```bash
claude mcp remove my-server -s user
```
### 列出 MCP 服务器
```bash
claude mcp list
```
## 项目配置审批
### 项目配置审批
`.mcp.json` 中的项目配置需要用户显式审批才能生效：
@@ -192,28 +180,20 @@ for (const [name, config] of Object.entries(projectServers)) {
首次打开项目时，Claude Code 会提示用户审批 `.mcp.json` 中的每个服务器。审批状态持久化在本地配置中。
## 插件 MCP 集成
### 插件 MCP 集成
插件通过 manifest 中的 `.mcp.json` 或 `.mcpb` 文件声明 MCP 服务器：
插件通过 manifest 中的 `.mcp.json` 或 `.mcpb` 文件声明 MCP 服务器。
```typescript
// 插件 MCP 加载流程
const pluginResult = await loadAllPluginsCacheOnly()
const pluginServerResults = await Promise.all(
pluginResult.enabled.map(plugin => getPluginMcpServers(plugin, mcpErrors))
)
```
### 插件命名空间
#### 插件命名空间
插件 MCP 服务器名格式为 `plugin:<pluginName>:<serverName>`，不会与手动配置的名称冲突。
### 去重机制
#### 去重机制
插件服务器通过内容签名去重（`dedupPluginMcpServers`）：
- **stdio 类型**：签名 = `stdio:` + JSON.stringify([command, ...args])
- **URL 类型**：签名 = `url:` + 原始 URL（unwrap CCR proxy URL）
- **URL 类型**：签名 = `url:` + 原始 URL
- **sdk 类型**：签名为 null，不去重
去重规则：
@@ -221,15 +201,9 @@ const pluginServerResults = await Promise.all(
2. 先加载的插件优先于后加载的
3. 被抑制的插件服务器在 `/plugin` UI 中显示提示
### claude.ai 连接器去重
### 策略管控
claude.ai 连接器使用相同的内容签名机制去重（`dedupClaudeAiMcpServers`）：
- 仅启用的手动配置参与去重（禁用的手动配置不应抑制连接器）
- 连接器名格式为 `claude.ai <DisplayName>`
## 策略管控
### Allowlist / Denylist
#### Allowlist / Denylist
企业策略通过 allowlist 和 denylist 控制可用的 MCP 服务器：
@@ -248,11 +222,11 @@ for (const [name, serverConfig] of Object.entries(configs)) {
- stdio 类型的 command + args 匹配
- URL 类型的 URL 模式匹配（支持通配符）
### 插件专用模式
#### 插件专用模式
`isRestrictedToPluginOnly('mcp')` 启用时，只允许插件提供的 MCP 服务器——用户/项目级配置被忽略。
## 环境变量展开
### 环境变量展开
MCP 配置中的环境变量支持 `$VAR` 和 `${VAR}` 语法展开：
@@ -271,55 +245,17 @@ MCP 配置中的环境变量支持 `$VAR` 和 `${VAR}` 语法展开：
展开时缺失的变量会生成警告信息，但不阻止配置加载。
## 内置 MCP 动态注册
### 内置 MCP 动态注册
内置 MCP 服务器在 `main.tsx` 启动流程中动态注入配置：
### Computer Use MCP
| 服务器 | 名称 | Feature Flag | 启用方式 |
|--------|------|-------------|---------|
| Computer Use | `computer-use` | `CHICAGO_MCP` | GrowthBook gate + macOS + interactive |
| Claude in Chrome | `claude-in-chrome` | — | `--chrome` 参数或配置 |
| VSCode SDK | `claude-vscode` | — | IDE 嵌入模式 (type:`sdk`) |
```typescript
// src/utils/computerUse/setup.ts
export function setupComputerUseMCP(): {
mcpConfig: Record<string, ScopedMcpServerConfig>
allowedTools: string[]
} {
return {
mcpConfig: {
"computer-use": {
type: "stdio",
command: process.execPath,
args: ["--computer-use-mcp"],
scope: "dynamic",
}
},
allowedTools: ["mcp__computer-use__screenshot", ...]
}
}
```
启用条件：
- Feature flag `CHICAGO_MCP` 开启
- `getPlatform() !== "unknown"`（macOS/Windows/Linux）
- 非非交互式会话
- GrowthBook gate `getChicagoEnabled()` 返回 true
### Claude in Chrome MCP
```typescript
// 类似 Computer Use，在 main.tsx 中注册
const { mcpConfig, allowedTools, systemPrompt } = setupClaudeInChrome()
dynamicMcpConfig = { ...dynamicMcpConfig, ...mcpConfig }
```
启用条件：
- `--chrome` 参数或 `claudeInChromeDefaultEnabled` 配置
- Chrome 扩展已安装
### VSCode SDK MCP
IDE 嵌入模式通过初始化消息传入 `type:'sdk'` 的配置，由 `setupVscodeSdkMcp()` 设置双向通知。
## 保留名称
### 保留名称
以下 MCP 服务器名称被保留，用户无法手动配置同名服务器：
@@ -333,7 +269,7 @@ IDE 嵌入模式通过初始化消息传入 `type:'sdk'` 的配置，由 `setupV
1. `addMcpConfig()`（`config.ts:636-648`）— 运行时拒绝
2. `main.tsx` 启动检查（`main.tsx:2351-2368`）— 启动时退出
## 关键源文件索引
### 关键源文件索引
| 文件 | 职责 |
|------|------|
@@ -344,3 +280,10 @@ IDE 嵌入模式通过初始化消息传入 `type:'sdk'` 的配置，由 `setupV
| `src/utils/computerUse/setup.ts` | Computer Use 动态注册 |
| `src/utils/claudeInChrome/common.ts` | Chrome MCP 保留名与工具名 |
| `src/services/mcp/vscodeSdkMcp.ts` | VSCode SDK 双向通知 |
## 关联笔记
- [[mcp-protocol|MCP 协议]]
- [[custom-agents|自定义 Agent]]
- [[skills|Skills 技能系统]]
- [[hooks|Hooks 生命周期钩子]]