​

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

{
  "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

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). Ensure Settings → Installation → Base URL matches this domain so MCP requests and OAuth callbacks resolve correctly.
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.

{
  "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.

​

HTTP Token Endpoints in Private Networks

{
  "mcpServers": {
    "internal-gitlab": {
      "type": "streamable-http",
      "url": "http://gitlab.internal.example/api/v4/mcp",
      "oauth": {
        "allowInsecureTokenEndpoint": true
      }
    }
  }
}

​

Configuration Options

​

Basic Auto Detection (Minimal Config)

{
  "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)

{
  "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 overrides the callback derived from Settings → Installation → Base URL for that server.
• If redirectUri is omitted, MCPHub falls back to ${Base URL}/oauth/callback, then to http://localhost:3000/oauth/callback.
• Keep Settings → Installation → Base URL aligned with your deployed domain so the default callback URL is correct.

​

Dynamic Client Registration (RFC 7591)

{
  "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.
• If oauth.redirectUri is provided, MCPHub uses it as the preferred callback URI and includes it in the dynamically registered redirect_uris.
• 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 – MCPHub persists expires_in as an absolute accessTokenExpiresAt timestamp. Before returning an expired token to the transport, it renews through the SDK and saves the rotated refresh token. Shared tokens use server settings; personal tokens remain in the user’s encrypted binding. Expiry survives runtime recreation, and concurrent personal renewals for the same binding revision within one MCPHub process share one refresh.

​

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.

​

Explicit authorization server metadata

{
  "type": "streamable-http",
  "url": "http://mcp-internal:3000/mcp",
  "oauth": {
    "identityMode": "personal",
    "clientId": "${OAUTH_CLIENT_ID}",
    "clientSecret": "${OAUTH_CLIENT_SECRET}",
    "redirectUri": "https://hub.example.com/oauth/callback",
    "scopes": ["User.Read", "offline_access"],
    "authorizationServerMetadata": {
      "issuer": "https://auth.example.com/tenant",
      "authorization_endpoint": "https://auth.example.com/tenant/authorize",
      "token_endpoint": "https://auth.example.com/tenant/token",
      "response_types_supported": ["code"],
      "code_challenge_methods_supported": ["S256"],
      "token_endpoint_auth_methods_supported": ["client_secret_post"]
    }
  }
}

​

Private broker authorization relay

{
  "type": "streamable-http",
  "url": "http://broker.internal:3000/mcp",
  "oauth": {
    "identityMode": "personal",
    "clientId": "${BROKER_CLIENT_ID}",
    "clientSecret": "${BROKER_CLIENT_SECRET}",
    "redirectUri": "https://hub.example.com/oauth/callback",
    "allowInsecureTokenEndpoint": true,
    "authorizationServerMetadata": {
      "issuer": "http://broker.internal:3000",
      "authorization_endpoint": "http://broker.internal:3000/authorize",
      "token_endpoint": "http://broker.internal:3000/token",
      "response_types_supported": ["code"],
      "code_challenge_methods_supported": ["S256"]
    },
    "authorizationRelay": {
      "allowedRedirectOrigins": ["https://login.microsoftonline.com"]
    }
  }
}

​

Remembering Downstream Application Consent

{
  "systemConfig": {
    "oauthServer": {
      "alwaysShowApprovalScreen": false,
      "approvalLifetime": 1209600
    }
  }
}

• GET /api/oauth/approvals returns { "success": true, "data": [...] }; each entry includes id, clientId, scopes, resource, redirectUri, approvedAt, and expiresAt.
• DELETE /api/oauth/approvals/:approvalId revokes all approvals and existing tokens for that entry’s application and current user, including pending authorization codes. Another user’s entry returns 404. MCP OAuth access tokens cannot authenticate these management APIs.