What It Is#
A three-package framework for putting OAuth 2.0 in front of MCP servers. The MCP spec leaves auth as an exercise for the implementer; these packages handle the exercise.
- mcp-authflow — the authorization server. Token issuance, introspection, storage (Postgres or in-memory), client validation, rate limiting.
- mcp-authflow-resource — the resource server. Token verification via RFC 7662 introspection, OAuth discovery endpoints (RFC 9728, RFC 8414, OIDC), and a friction-control feedback loop that throttles tool calls dynamically.
- example-mcp-server — a runnable docker compose stack wiring both halves together with a notes CRUD API.
Why Two Packages#
OAuth 2.0 separates authorization servers from resource servers for good reasons: different trust boundaries, different scaling needs, different deploy targets. Most MCP auth implementations collapse them into one process and lose that property. Splitting the framework along the same line keeps deployments honest.
Friction Control#
The resource server includes a proportional feedback loop on tool-call rates. Instead of a hard rate limit, it adds latency proportional to recent volume — clients self-throttle without seeing 429s. Useful for agentic clients that retry aggressively.
Why I Built It#
I needed OAuth on the MCP servers powering my agents. The existing options either didn't separate auth and resource concerns, didn't ship discovery endpoints, or weren't pip-installable. I pulled what I had into clean packages with examples that work out of the box with Claude Code, Claude Desktop, and Cursor.