OAuth 2.1 Flow

The Hype Doc MCP server uses OAuth 2.1 with PKCE for authentication, following the MCP specification. Most MCP clients handle this flow automatically.

Discovery endpoints

MCP clients discover the OAuth configuration using well-known endpoints:

Protected Resource Metadata

GET https://app.myhypedoc.com/.well-known/oauth-protected-resource

Returns the resource server metadata, including the authorization server URL.

Authorization Server Metadata

GET https://app.myhypedoc.com/.well-known/oauth-authorization-server

Returns the full OAuth server configuration, including:

• Authorization endpoint
• Token endpoint
• Supported grant types
• Supported response types
• PKCE code challenge methods

Flow overview

1. Client discovers endpoints via .well-known metadata
2. Client generates a PKCE code verifier and derives the code challenge
3. Client redirects the user to the authorization endpoint with the code challenge
4. User authorizes Hype Doc in their browser
5. Authorization server redirects back with an authorization code
6. Client exchanges the code for an access token (including the code verifier)
7. Client uses the access token in the Authorization: Bearer header for MCP requests

Token usage

Once authorized, the MCP client includes the access token in every request:

POST /mcp HTTP/1.1
Host: app.myhypedoc.com
Authorization: Bearer oauth_access_token_here
Content-Type: application/json

Doorkeeper (OAuth provider)

Hype Doc uses Doorkeeper as its OAuth 2.1 provider. The standard Doorkeeper endpoints are available:

Endpoint	Path
Authorization	/oauth/authorize
Token	/oauth/token
Revocation	/oauth/revoke

Rate limits

OAuth-authenticated MCP requests are limited to 60 requests per minute per token. See Rate Limits.