# mcp_admin 原则与核心概念

## 模板（原则）

### 设计目标

- <目标 1>
- <目标 2>

### 契约原则

- <输入/输出契约规则>

### 安全与边界

- <访问约束/护栏>

### 失败与恢复

- <调用失败时的行动>

### 术语表

- <该工具集特有术语>

## 核心概念

### 1. MCP 连接管理

MCP（Model Context Protocol）是连接外部服务的协议。

**功能：**

- 启动 MCP 服务
- 重启 MCP 连接
- 释放 MCP 资源

### 2. MCP 租约

MCP 使用租约机制管理连接/进程资源，例如 HTTP 连接和 stdio 进程。租约只表示谁持有某个连接/进程，不决定 MCP 工具的全局注册或可见性。

**生命周期：**

- **获取租约**：建立或持有一个连接/进程
- **持有租约**：继续使用该连接/进程
- **释放租约**：停止/断开并释放资源

`mcp_restart` 会把目标 server 的 `enabled: false` 改回 `enabled: true`，然后尝试启动；成功时会替换全局 MCP 服务连接，并清掉旧连接/进程的所有对话 lease；不需要先逐个 `mcp_release`。如果需要强制禁用某个 server，使用 `mcp_disable`。

### 3. 环境变量

与 os 工具集共享环境变量功能。

## 工具概览

| 工具        | 功能                |
| ----------- | ------------------- |
| mcp_restart | 启用并重启 MCP 服务 |
| mcp_release | 释放 MCP 租约       |
| mcp_disable | 禁用 MCP 服务       |
| env_get     | 获取环境变量        |
| env_set     | 设置环境变量        |
| env_unset   | 删除环境变量        |

## 最佳实践

### 1. MCP 连接管理

- **及时释放**：不再使用 MCP 时及时释放租约
- **监控状态**：定期检查 MCP 连接状态
- **错误处理**：处理连接失败的情况
- **职责路由**：没有 `mcp_admin` 工具集的队友遇到 MCP 工具异常时，应按团队职责速查表/路由卡找到 MCP 排障或管理员队友协助，不要自行绕过。

### 2. 资源管理

- **避免泄漏**：确保所有获取的租约都被释放
- **重试机制**：实现重试逻辑处理临时故障

## 限制与注意事项

1. MCP 连接可能需要特定配置
2. 租约有有效期限制
3. 某些 MCP 服务可能需要认证
