mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-23 18:29:21 -05:00
Add OAuth support for upstream MCP servers (#381)
Co-authored-by: samanhappy <samanhappy@gmail.com>
This commit is contained in:
Copilot
@@ -27,7 +27,8 @@
|
||||
"pages": [
|
||||
"features/server-management",
|
||||
"features/group-management",
|
||||
"features/smart-routing"
|
||||
"features/smart-routing",
|
||||
"features/oauth"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -57,7 +58,8 @@
|
||||
"pages": [
|
||||
"zh/features/server-management",
|
||||
"zh/features/group-management",
|
||||
"zh/features/smart-routing"
|
||||
"zh/features/smart-routing",
|
||||
"zh/features/oauth"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -159,4 +161,4 @@
|
||||
"discord": "https://discord.gg/qMKNsn5Q"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
141
docs/features/oauth.mdx
Normal file
141
docs/features/oauth.mdx
Normal file
@@ -0,0 +1,141 @@
|
||||
# OAuth Support
|
||||
|
||||
## At a Glance
|
||||
- Covers end-to-end OAuth 2.0 Authorization Code with PKCE for upstream MCP servers.
|
||||
- Supports automatic discovery from `WWW-Authenticate` responses and RFC 8414 metadata.
|
||||
- Implements dynamic client registration (RFC 7591) and resource indicators (RFC 8707).
|
||||
- Persists client credentials and tokens to `mcp_settings.json` for reconnects.
|
||||
|
||||
## When MCPHub Switches to OAuth
|
||||
1. MCPHub calls an MCP server that requires authorization and receives `401 Unauthorized`.
|
||||
2. The response exposes a `WWW-Authenticate` header pointing to protected resource metadata (`authorization_server` or `as_uri`).
|
||||
3. MCPHub discovers the authorization server metadata, registers (if needed), and opens the browser so the user can authorize once.
|
||||
4. After the callback is handled, MCPHub reconnects with fresh tokens and resumes requests transparently.
|
||||
|
||||
> MCPHub logs each stage (discovery, registration, authorization URL, token exchange) in the server detail view and the backend logs.
|
||||
|
||||
## Quick Start by Server Type
|
||||
|
||||
### Servers with Dynamic Registration Support
|
||||
Some servers expose complete OAuth metadata and allow dynamic client registration. For example, Vercel and Linear MCP servers only need their SSE endpoint configured:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"vercel": {
|
||||
"type": "sse",
|
||||
"url": "https://mcp.vercel.com"
|
||||
},
|
||||
"linear": {
|
||||
"type": "sse",
|
||||
"url": "https://mcp.linear.app/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- MCPHub discovers the authorization server, registers the client, and handles PKCE automatically.
|
||||
- Tokens are stored in `mcp_settings.json`; no additional dashboard configuration is needed.
|
||||
|
||||
### Servers Requiring Manual Client Provisioning
|
||||
Other providers do not support dynamic registration. GitHub’s MCP endpoint (`https://api.githubcopilot.com/mcp/`) is one example. To connect:
|
||||
|
||||
1. Create an OAuth App in the provider’s console (for GitHub, go to **Settings → Developer settings → OAuth Apps**).
|
||||
2. Set the callback/redirect URL to `http://localhost:3000/oauth/callback` (or your deployed dashboard domain).
|
||||
3. Copy the issued client ID and client secret.
|
||||
4. Supply the credentials through the MCPHub dashboard or by editing `mcp_settings.json` as shown below.
|
||||
|
||||
```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 skips dynamic registration and uses the credentials you provide to complete the OAuth exchange.
|
||||
- Update the dashboard or configuration file whenever you rotate secrets.
|
||||
- Replace `scopes` with the exact scope strings required by the provider.
|
||||
|
||||
## Configuration Options
|
||||
You can rely on auto-detection for most servers or declare OAuth settings explicitly in `mcp_settings.json`. Only populate the fields you need.
|
||||
|
||||
### Basic Auto Detection (Minimal Config)
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"secured-sse": {
|
||||
"type": "sse",
|
||||
"url": "https://mcp.example.com/sse",
|
||||
"oauth": {
|
||||
"scopes": ["mcp.tools", "mcp.prompts"],
|
||||
"resource": "https://mcp.example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
- MCPHub will discover the authorization server from challenge headers and walk the user through authorization automatically.
|
||||
- Tokens (including refresh tokens) are stored on disk and reused on restart.
|
||||
|
||||
### Static Client Credentials (Bring Your Own 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
- Use this when the authorization server requires manual client provisioning.
|
||||
- `redirectUri` defaults to `http://localhost:3000/oauth/callback`; override it when running behind a custom domain.
|
||||
|
||||
### Dynamic Client Registration (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 discovers endpoints via `issuer`, registers itself, and persists the issued `client_id`/`client_secret`.
|
||||
- Provide `initialAccessToken` only when the registration endpoint is protected.
|
||||
|
||||
## Authorization Flow
|
||||
1. **Initialization** – On startup MCPHub processes every server entry, discovers metadata, and registers the client if `dynamicRegistration.enabled` is true.
|
||||
2. **User Authorization** – Initiating a connection launches the system browser to the server’s authorize page with PKCE parameters.
|
||||
3. **Callback Handling** – The built-in route (`/oauth/callback`) verifies the `state`, completes the token exchange, and saves the tokens via the MCP SDK.
|
||||
4. **Token Lifecycle** – Access and refresh tokens are cached in memory, refreshed automatically, and written back to `mcp_settings.json`.
|
||||
|
||||
## Tips & Troubleshooting
|
||||
- Confirm that the redirect URI used during authorization exactly matches one of the `redirect_uris` registered with the authorization server.
|
||||
- When running behind HTTPS, expose the callback URL publicly or configure a reverse proxy at `/oauth/callback`.
|
||||
- If discovery fails, supply `authorizationEndpoint` and `tokenEndpoint` explicitly to bypass metadata lookup.
|
||||
- Remove stale tokens from `mcp_settings.json` if an authorization server revokes access—MCPHub will prompt for a fresh login on the next request.
|
||||
141
docs/zh/features/oauth.mdx
Normal file
141
docs/zh/features/oauth.mdx
Normal file
@@ -0,0 +1,141 @@
|
||||
# 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`（或你的部署域名）。
|
||||
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 会在下一次请求时重新触发授权。
|
||||
Reference in New Issue
Block a user