mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 14:25:51 +00:00
cda7703ec4
移除 TypeScript 代码、源码路径和传输层实现细节， 聚焦多来源合并的企业管控设计、内置vs外部的架构一致性、 工具描述截断的防护和 disallowedTools 黑名单优先的安全思维。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
85 lines
3.4 KiB
Plaintext
85 lines
3.4 KiB
Plaintext
---
|
||
title: "MCP 配置"
|
||
description: "MCP 服务器从多个来源汇聚配置。理解多来源合并、企业排他模式、项目配置审批和保留名称机制。"
|
||
keywords: ["MCP", "配置", "settings.json", ".mcp.json", "企业策略"]
|
||
---
|
||
|
||
## 核心问题
|
||
|
||
MCP（Model Context Protocol）让 Claude Code 可以使用外部工具——数据库查询、浏览器控制、API 调用等。但 MCP 配置来自多个来源：用户全局、项目级、插件、企业策略。如何合并？谁优先？
|
||
|
||
## 配置来源与合并优先级
|
||
|
||
配置按优先级从低到高合并，高优先级覆盖低优先级：
|
||
|
||
```
|
||
claude.ai 连接器（最低） → 插件 → 用户全局 → 项目配置 → 本地项目 → 内置动态（最高）
|
||
```
|
||
|
||
| 来源 | Scope | 说明 |
|
||
|------|-------|------|
|
||
| claude.ai 连接器 | `claudeai` | 网页端配置的远程连接器 |
|
||
| 插件 | `dynamic` | 插件 manifest 中声明 |
|
||
| 用户全局 | `user` | `~/.claude/settings.json` |
|
||
| 项目配置 | `project` | `.mcp.json`（需审批） |
|
||
| 本地项目 | `local` | `settings.local.json`（不提交 VCS） |
|
||
| 内置动态 | `dynamic` | Computer Use 等内置服务器 |
|
||
|
||
## 企业排他模式
|
||
|
||
当企业管理员部署 `managed-mcp.json` 时，进入**排他模式**：只使用企业配置，忽略所有用户、项目、插件和 claude.ai 配置。
|
||
|
||
**设计考量**：企业环境需要严格控制 AI 可以访问哪些外部工具。排他模式确保用户不能绕过企业策略添加自己的 MCP 服务器。
|
||
|
||
## 项目配置审批
|
||
|
||
`.mcp.json` 是项目级共享配置（可提交到 git），但需要用户显式审批才能生效。
|
||
|
||
**为什么需要审批**？项目配置可能由任何人修改（包括恶意贡献者）。审批机制确保用户知情并同意项目提供的 MCP 服务器连接到他们的环境。
|
||
|
||
审批状态持久化在本地配置中，不需要每次重新审批。
|
||
|
||
## 传输类型
|
||
|
||
MCP 服务器通过不同的传输方式连接：
|
||
|
||
| 类型 | 适用场景 | 配置方式 |
|
||
|------|---------|---------|
|
||
| **stdio** | 本地工具（启动子进程） | `command` + `args` |
|
||
| **SSE** | 远程 Server-Sent Events | `url` + 可选 `headers` |
|
||
| **HTTP** | HTTP 流式传输 | `url` + 可选 `headers` |
|
||
| **WebSocket** | 双向实时通信 | `wss://` URL |
|
||
|
||
stdio 类型最常见——它启动一个本地子进程，通过 stdin/stdout 通信。远程类型（SSE/HTTP/WS）用于连接远程服务。
|
||
|
||
### 认证
|
||
|
||
远程 MCP 服务器支持 OAuth 认证。认证失败时进入 `needs-auth` 状态，15 分钟内不重复提示。
|
||
|
||
## 插件集成
|
||
|
||
插件通过 manifest 声明 MCP 服务器，命名空间为 `plugin:<pluginName>:<serverName>`，不会与手动配置冲突。
|
||
|
||
插件服务器通过内容签名去重：
|
||
- stdio 类型：基于 command + args
|
||
- URL 类型：基于 URL
|
||
- 手动配置优先于插件配置
|
||
|
||
## 策略管控
|
||
|
||
企业策略通过 allowlist 和 denylist 控制可用的 MCP 服务器。策略检查不仅匹配服务器名称，还匹配 command/args（stdio）和 URL 模式（远程）。
|
||
|
||
## 保留名称
|
||
|
||
以下名称被保留，用户无法手动配置：
|
||
- `claude-in-chrome` — Chrome 浏览器控制
|
||
- `computer-use` — 桌面自动化
|
||
|
||
这防止用户意外覆盖内置服务器的配置。
|
||
|
||
## 接下来
|
||
|
||
- **MCP 协议** — 理解连接管理、工具发现和执行链路
|
||
- **Hooks** — 理解 MCP 生命周期中的 Hook 集成
|
||
- **自定义 Agent** — 理解 Agent 中引用 MCP 服务器
|