MCP OAuth 身份验证
将 Bob Shell 连接到需要用户委托访问的 MCP 服务器（使用 OAuth 2.1）。Bob Shell 负责管理身份验证和令牌刷新流程，因此你无需手动管理令牌。
有关通用 MCP 配置，请参阅配置 MCP 服务器。
概述
你可以将 Bob Shell 连接到代表你执行操作的模型上下文协议 (MCP) 服务器，例如访问你的代码仓库、云资源或企业服务。这些服务器使用 OAuth 2.1，以便你可以登录并批准访问。
Bob Shell 直接管理身份验证流程。当你配置需要 OAuth 的服务器时，Bob Shell 会在你的默认浏览器中打开授权窗口。在你登录并批准权限后，Bob Shell 会存储并刷新你的访问令牌，无需你手动处理凭据。
在以下情况下使用 OAuth：
- 你需要访问与你的个人或企业用户账户关联的资源
- 服务器使用需要自动刷新令牌的短期令牌
- 你希望将静态凭据和机密信息保留在配置文件之外
当你已经拥有永不过期的静态 API 令牌或个人访问令牌时，可以改用 headers 中的 Bearer 令牌。
身份验证流程的工作原理
- 你将远程 MCP 服务器 URL 添加到配置文件中，无需
headers或env凭据。 - 当 Bob Shell 连接到服务器时，Bob Shell 会检测到 OAuth 要求。
- Bob Shell 打开浏览器登录窗口，你可以在其中查看请求的权限并批准访问。
- Bob Shell 接收授权令牌并在你的会话之间安全地存储它们。
- Bob Shell 会在令牌过期之前自动刷新，以便你可以不间断地工作。
Bob Shell Authorization Server MCP Server
| | |
|-- connect to server ---------->| |
|<-- OAuth metadata (401) -------| |
|-- open auth prompt ----------->| |
| (user signs in & consents) | |
|<-- authorization code ---------| |
|-- exchange for tokens -------->| |
|<-- access + refresh tokens ----| |
|-- authenticated requests ---------------------------------> |
| (auto-refresh when needed) |配置启用 OAuth 的服务器
你可以在全局配置 (~/.bob/mcp_settings.json) 或项目配置 (.bob/mcp.json) 中配置 MCP 服务器。
最小配置（自动发现）
当你的 MCP 服务器提供自动 OAuth 元数据发现时，只需指定 url：
{
"mcpServers": {
"my-oauth-server": {
"url": "https://mcp.example.com/mcp"
}
}
}Bob Shell 会在连接时检测 OAuth 要求并指导你完成浏览器登录流程。
自定义 OAuth 参数
当你的身份提供商需要预注册的客户端 ID、自定义作用域或客户端密钥时，配置 oauth 对象：
{
"mcpServers": {
"my-oauth-server": {
"url": "https://mcp.example.com/mcp",
"oauth": {
"enabled": true,
"clientId": "your-client-id-from-idp",
"clientSecret": "your-client-secret-if-required",
"scope": "mcp:connect read:data"
}
}
}
}配置属性
| 属性 | 类型 | 描述 |
|---|---|---|
url | string | 远程 MCP 端点 URL（必需）。 |
oauth.enabled | boolean | 设置为 false 以禁用 OAuth，或设置为 true 以要求 OAuth。未提供 Authorization 标头时默认启用。 |
oauth.clientId | string | 你的身份提供商颁发的预注册 OAuth 客户端 ID。 |
oauth.clientSecret | string | OAuth 客户端密钥（如果你的授权服务器对机密客户端有此要求）。 |
oauth.scope | string | 要请求的 OAuth 作用域的空格分隔列表。 |
向 MCP 服务器配置添加静态 Authorization 标头会关闭 OAuth。当存在 Authorization 标头时，Bob Shell 不会启动 OAuth 流程。当 OAuth 处于活动状态时，Bob Shell 会在发送请求之前删除静态 Authorization 标头。每个服务器仅使用一种身份验证方法。
向你的身份提供商注册 Bob
当你的身份提供商 (IdP) 要求你在连接之前将 Bob 注册为客户端应用程序时，请使用以下应用程序设置：
| 设置 | 值 |
|---|---|
| 应用程序或客户端类型 | 公共、原生或 Loopback（带 PKCE 的授权码） |
| 重定向 URI | http://127.0.0.1:33418/callback |
| 其他重定向 URI | http://127.0.0.1:33419/callback 至 http://127.0.0.1:33427/callback（如果端口 33418 被占用，建议配置） |
| 授权类型 | 授权码 (authorization_code) 和刷新令牌 (refresh_token) |
| 作用域 | MCP 服务器文档中指定的作用域 |
将颁发的客户端 ID 复制到配置文件中的 oauth.clientId。
在提示时进行身份验证
当你首次连接到启用 OAuth 的服务器时：
- 浏览器窗口打开，显示授权提示。
- 查看服务器请求的权限。
- 登录你的账户并批准访问。
- Bob Shell 会保存你的凭据并自动连接到服务器工具。
故障排除
身份验证提示未打开
- 验证你在配置中未将服务器标记为已禁用。
- 检查你的配置文件在
headers中未包含静态Authorization标头。 - 重启 Bob Shell 以重新启动连接。
- 检查你的浏览器或防火墙未阻止
127.0.0.1上的本地环回连接。
身份提供商返回重定向 URI 不匹配错误
- 验证你的身份提供商客户端注册中包含
http://127.0.0.1:33418/callback。 - 如果端口 33418 繁忙，请注册从
33419到33427的其他端口。
身份验证成功但服务器无法连接
- 验证服务器 URL 是否正确且可从你的网络访问。
- 检查你在登录步骤中是否批准了所有必需的作用域。
- 查看服务器日志或文档以了解先决用户角色或权限要求。
令牌频繁过期且必须重新进行身份验证
- 确认你的授权服务器颁发刷新令牌。
- 检查你的系统时钟是否同步，以防止令牌过早过期。
你想注销或切换账户
在配置文件中删除或重命名服务器条目，然后重新添加。Bob Shell 会将其视为新服务器，并在下次连接时提示你登录。