接入与管理 MCP

选择服务类型

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

Bridge 传递外部 MCP 配置，运行时负责与服务交互。进程内 MCP 则把调用交回宿主 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 服务的标准输出应留给协议，日志写标准错误。

确认连接状态

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 工具的开发与验证见自定义工具。