An OAuth 2.1 authorization server that bridges MCP clients to GitHub login.
MCP clients speak standard OAuth to us — RFC 8414 metadata, RFC 7591 dynamic
client registration, PKCE authorization-code — and we use GitHub (via Assent,
the DB-free client lib pow_assent wraps) as the upstream identity. GitHub
can't be an MCP authorization server directly (no metadata endpoint, no DCR,
no PKCE public clients), which is why this bridge exists.
Every artifact (client_id, state, code, access token) is a stateless macaroon
(OAuthMCPBridge.Artifact); nothing is persisted, so it survives scale-to-zero.
Configuration
Set these via :persistent_term before starting (e.g. in your
Application.start/2):
{:oauth_mcp_bridge, :github}—%{client_id: ..., client_secret: ...}{:oauth_mcp_bridge, :auth}—%{logins: MapSet, orgs: MapSet}(seeOAuthMCPBridge.Whitelist.parse/1){:oauth_mcp_bridge, :token_secret}— the macaroon root key{:oauth_mcp_bridge, :service}(optional) —%{name: "...", documentation_url: "...", mcp_path: "/mcp"}; defaults to a generic "MCP Server" identity and/mcp.
Summary
Functions
Validate an /authorize request and return the GitHub URL to redirect the user
to. PKCE (S256) is required; client_id and redirect_uri must match a
registration.
Handle GitHub's redirect: verify our signed state, exchange the code with GitHub, resolve + whitelist the login, and return a redirect back to the client's redirect_uri carrying our authorization code (or an error).
Register a public client; the client_id is a macaroon carrying its redirect_uris.
Handle the token endpoint: exchange an authorization code (+ PKCE verifier) for an access + refresh token, or silently renew from a refresh token (no GitHub round-trip).
Verify an MCP bearer access token; returns the GitHub login.
Functions
Validate an /authorize request and return the GitHub URL to redirect the user
to. PKCE (S256) is required; client_id and redirect_uri must match a
registration.
Handle GitHub's redirect: verify our signed state, exchange the code with GitHub, resolve + whitelist the login, and return a redirect back to the client's redirect_uri carrying our authorization code (or an error).
Register a public client; the client_id is a macaroon carrying its redirect_uris.
Handle the token endpoint: exchange an authorization code (+ PKCE verifier) for an access + refresh token, or silently renew from a refresh token (no GitHub round-trip).
Verify an MCP bearer access token; returns the GitHub login.