mcp-frontdesk
A small OAuth 2.1 authorization server and access-token gate for MCP servers. It signs people in to your MCP server the way the MCP authorization specification asks: clients identify themselves with a Client ID Metadata Document, every code needs PKCE S256, and refresh tokens rotate on every use. It is for when you want to be your own authorization server, with your accounts, your consent page and your database. It began as the sign-in layer of our own MCP server.
Quick start
- install
npm install mcp-frontdeskAdds the library to your project, and nothing else. Needs Node.js 22.18 or later. - run the example
git clone https://github.com/distronode-corporation/mcp-frontdesk.git cd mcp-frontdesk npm ci && npm run build cd examples/basic-server npm ci npm startBuilds the cloned repository and serves an example MCP server on your own machine: a demo sign-in, a consent page, and three tools over made-up notes. - test it
npm testIn the same folder, once npm start is stopped or from a second terminal. The end-to-end test: discovery, sign-in with PKCE, tool calls, a refresh, then a replayed refresh token that revokes the connection; an access token already issued works until it expires.
The README's install line and its Example server commands. Its Quick start shows the code that puts mcp-frontdesk in front of your own server.
What it gives your MCP server
Framework-free, on your storage
Every endpoint takes a Web Request and returns a Response, and its one runtime dependency is jose. Your storage sits behind two small interfaces: in-memory stores ship in the package, and a contract test suite checks your own. There are no product defaults: you configure every URL, scope, client host and redirect URI.
Guarded where anyone can reach it
The client metadata fetch goes through an SSRF guard, on by default, and request bodies are capped as they stream in. Every refused code or refresh token gets the same answer, so the token endpoint gives nothing away. By default, a rotated refresh token presented again revokes its whole family. Stores only ever see SHA-256 hashes, and access tokens carry no email unless you add one.
Beside the official SDK
The official MCP TypeScript SDK serves the protocol and the bearer gate, and keeps its own authorization-server helpers in a legacy package. mcp-frontdesk is the authorization server: discovery, the authorize checks, codes and the token endpoint. Its authenticate call gates the MCP route, and the SDK serves MCP behind it. The sign-in and consent pages stay yours.
- Licence
- Apache-2.0
- Built with
- TypeScript, ESM, on Node.js 22.18 or later
- Standards
- OAuth 2.1, Client ID Metadata Documents, PKCE S256, and the protected resource (RFC 9728) and authorization server (RFC 8414) metadata
- Not included
- Dynamic client registration, a JWKS endpoint, confidential clients, and any sign-in or consent screen
- Install
- npm install mcp-frontdesk. A runnable example server is in the repository, not in the package
- Status
- Released on npm with a provenance attestation. The API may still change before 1.0; read its SECURITY-MODEL.md before you put it in front of real accounts
Get involved
Issues and pull requests are welcome on GitHub. Report a vulnerability privately, as the security policy describes, and not in a public issue.
- Contributing guide
- CONTRIBUTING.md
- Security policy
- SECURITY.md
- Changelog
- CHANGELOG.md

