# 接入与管理 MCP

连接 stdio、HTTP 和进程内服务，排查发现、认证与工具调用问题。

## 选择服务类型

| 类型 | 配置 | 适用情况 |
| --- | --- | --- |
| 本地子进程 | `mcp.StdioServerConfig` | 已有命令行 MCP 服务 |
| HTTP | `mcp.HTTPServerConfig` | 团队或云端 MCP 服务 |
| SSE | `mcp.SSEServerConfig` | 仍采用 SSE 的服务 |
| Go 进程内 | `WithCustomTools` 或 `WithSDKMCPServer` | 调用宿主业务函数 |

Bridge 传递外部 MCP 配置，运行时负责与服务交互。进程内 MCP 则把调用交回宿主 Go 代码。两条路径的执行身份、网络访问和凭据位置可能不同。

## 配置服务

```go
options = options.WithMCPServer("catalog", mcp.HTTPServerConfig{
    URL: "https://mcp.example.com/mcp",
}).WithMCPServer("local", mcp.StdioServerConfig{
    Command: "/opt/tools/catalog-mcp",
    Args: []string{"--read-only"},
})
```

这些地址和命令是占位示例，必须换成真实服务。Args 由该服务定义，不是 bridge 的通用参数。HTTP 服务需要凭据时，通过其约定的 Headers 或 OAuth 配置提供，不要把令牌拼进 URL。

给外部程序提供的 Env 应只包含它所需的值。安装或更新服务后，先在部署环境检查命令能否启动，再通过运行时检查工具发现。stdio 服务的标准输出应留给协议，日志写标准错误。

## 确认连接状态

```go
status, err := session.MCP().Status(ctx)
if err != nil { return err }
fmt.Printf("%+v\n", status)
```

这段输出仅用于本地排错。面向用户的页面应挑选服务名、连接状态和可操作的错误，不直接展示整个响应。

配置存在不等于工具已被发现；服务连接成功也不等于该工具获得调用许可。按“配置、连接、工具发现、权限、执行结果”的顺序检查。需要预先批准时使用完整工具名，例如 `mcp__catalog__lookup`。

## 动态修改服务

`session.MCP().SetServers(ctx, servers)` 替换当前 SDK 管理的服务集合，因此传入前应准备完整目标集合，而不是只传新增的一项并假设其余会保留。检查返回的 `SetServersResult` 和后续 Status，再更新界面。

`Reconnect` 重连单个服务，`SetEnabled` 启停指定服务。调用可能受运行时支持和服务状态影响；失败时保留旧状态并向用户解释原因，不要提前显示已成功。

## 认证流程

MCP 控制面提供 Authenticate、SubmitOAuthCallbackURL 和 ClearAuth。宿主负责展示登录入口、接收正确的回调，并避免把 OAuth 内容写入普通日志。

认证属于具体服务和用户，不能把管理员的凭据共享给所有用户。清除认证可能影响后续任务，执行前应明确目标服务和当前用户。

## 失败时先检查什么

| 现象 | 检查位置 |
| --- | --- |
| 找不到本地服务 | 命令路径、执行权限、运行身份 |
| 服务启动后立即退出 | stderr、缺失环境变量、参数是否正确 |
| HTTP 连接失败 | 服务地址、宿主网络、代理和证书 |
| 连接成功但没有工具 | 服务公开的工具列表、版本和发现结果 |
| 工具被拒绝 | 完整名称、允许规则和审批入口 |
| 调用一直等待 | 服务自身超时、网络请求和取消处理 |

Go 工具的开发与验证见[自定义工具](/docs/sdk-tools)。