# OAuth 支持
## 核心亮点
- 覆盖上游 MCP 服务器的 OAuth 2.0 授权码（PKCE）全流程。
- 支持从 `WWW-Authenticate` 响应和 RFC 8414 元数据自动发现。
- 实现动态客户端注册（RFC 7591）以及资源指示（RFC 8707）。
- 会将客户端凭据与令牌持久化到 `mcp_settings.json`，重启后直接复用。
## MCPHub 何时启用 OAuth
1. MCPHub 调用需要授权的 MCP 服务器并收到 `401 Unauthorized`。
2. 响应通过 `WWW-Authenticate` header 暴露受保护资源的元数据（`authorization_server` 或 `as_uri`）。
3. MCPHub 自动发现授权服务器、按需注册客户端，并引导用户完成一次授权。
4. 回调处理完成后，MCPHub 使用新令牌重新连接并继续请求。
> MCPHub 会在服务器详情视图和后端日志中记录发现、注册、授权链接、换取令牌等关键步骤。
## 按服务器类型快速上手
### 支持动态注册的服务器
部分服务器会公开完整的 OAuth 元数据，并允许客户端动态注册。例如 Vercel 与 Linear 的 MCP 服务器只需配置 SSE 地址即可：
```json
{
"mcpServers": {
"vercel": {
"type": "sse",
"url": "https://mcp.vercel.com"
},
"linear": {
"type": "sse",
"url": "https://mcp.linear.app/mcp"
}
}
}
```
- MCPHub 会自动发现授权服务器、完成注册，并处理整个 PKCE 流程。
- 所有凭据与令牌会写入 `mcp_settings.json`，无须在控制台额外配置。
### 需要手动配置客户端的服务器
另有一些服务端并不支持动态注册。GitHub 的 MCP 端点（`https://api.githubcopilot.com/mcp/`）就是典型例子，接入步骤如下：
1. 在服务提供商控制台创建 OAuth 应用（GitHub 路径为 **Settings → Developer settings → OAuth Apps**）。
2. 将回调/重定向地址设置为 `http://localhost:3000/oauth/callback`（或你的部署域名）。同时请确保 **设置 → 安装 → 基础地址** 与该域名一致，用于 MCP 请求与 OAuth 回调。
3. 复制生成的 Client ID 与 Client Secret。
4. 通过 MCPHub 控制台或直接编辑 `mcp_settings.json` 写入如下配置。
```json
{
"mcpServers": {
"github": {
"type": "sse",
"url": "https://api.githubcopilot.com/mcp/",
"oauth": {
"clientId": "${GITHUB_OAUTH_APP_ID}",
"clientSecret": "${GITHUB_OAUTH_APP_SECRET}",
"scopes": ["replace-with-provider-scope"],
"resource": "https://api.githubcopilot.com"
}
}
}
}
```
- MCPHub 会跳过动态注册，直接使用你提供的凭据完成授权流程。
- 凭据轮换时需要同步更新控制台或配置文件。
- 将 `scopes` 替换为服务端要求的具体 Scope。
## 配置方式
大多数场景可依赖自动检测，也可以在 `mcp_settings.json` 中显式声明 OAuth 配置。只填写确实需要的字段。
### 自动检测（最小配置）
```json
{
"mcpServers": {
"secured-sse": {
"type": "sse",
"url": "https://mcp.example.com/sse",
"oauth": {
"scopes": ["mcp.tools", "mcp.prompts"],
"resource": "https://mcp.example.com"
}
}
}
}
```
- MCPHub 会根据挑战头自动发现授权服务器，并引导用户完成授权。
- 令牌（包含刷新令牌）会写入磁盘，重启后自动复用。
### 静态客户端凭据（自带 Client）
```json
{
"oauth": {
"clientId": "mcphub-client",
"clientSecret": "replace-me-if-required",
"authorizationEndpoint": "https://auth.example.com/oauth/authorize",
"tokenEndpoint": "https://auth.example.com/oauth/token",
"redirectUri": "http://localhost:3000/oauth/callback"
}
}
```
- 适用于需要手动注册客户端的授权服务器。
- `redirectUri` 默认是 `http://localhost:3000/oauth/callback`，如在自定义域部署请同步更新。
- 同时确保 **设置 → 安装 → 基础地址** 与部署域名一致，以保证默认回调地址正确。
### 动态客户端注册（RFC 7591）
```json
{
"oauth": {
"dynamicRegistration": {
"enabled": true,
"issuer": "https://auth.example.com",
"metadata": {
"client_name": "MCPHub",
"redirect_uris": [
"http://localhost:3000/oauth/callback",
"https://mcphub.example.com/oauth/callback"
],
"scope": "mcp.tools mcp.prompts",
"grant_types": ["authorization_code", "refresh_token"]
},
"initialAccessToken": "optional-token-if-required"
},
"scopes": ["mcp.tools", "mcp.prompts"],
"resource": "https://mcp.example.com"
}
}
```
- MCPHub 会通过 `issuer` 发现端点、完成注册，并持久化下发的 `client_id`/`client_secret`。
- 只有当注册端点受保护时才需要提供 `initialAccessToken`。
## 授权流程
1. **初始化**：启动时遍历服务器配置，发现元数据并在启用 `dynamicRegistration` 时注册客户端。
2. **用户授权**：建立连接时自动打开系统浏览器，携带 PKCE 参数访问授权页。
3. **回调处理**：内置路径 `/oauth/callback` 校验 `state`、完成换取令牌，并通过 MCP SDK 保存结果。
4. **令牌生命周期**：访问令牌与刷新令牌会缓存于内存，自动刷新，并写回 `mcp_settings.json`。
## 提示与排障
- 确保授权过程中使用的回调地址与已注册的 `redirect_uris` 完全一致。
- 若部署在 HTTPS 域名下，请对外暴露 `/oauth/callback` 或通过反向代理转发。
- 如无法完成自动发现，可显式提供 `authorizationEndpoint` 与 `tokenEndpoint`。
- 授权服务器吊销令牌后，可手动清理 `mcp_settings.json` 中的旧令牌，MCPHub 会在下一次请求时重新触发授权。
