mcp-oauth2.1

Reference mcp server implementation of draft mcp oauth spec https://modelcontextprotocol.io/specification/draft/basic/authorization#2-3-authorization-server-discovery

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio quantgeekdev-mcp-oauth2.1-server node dist/index.js \
  --env PORT="1335 (default; override to 1335 if needed)" \
  --env PROTOCOL="https (recommended) or http"

How to use

This MCP server is a reference implementation of the draft Authorization specification for MCP. It provides an OAuth2.1-based authorization flow with support for two authentication providers: Cognito and Keycloak (self-hosted). The server validates the mcp:access scope against resource identifiers and enables clients to discover and authorize access to MCP resources via a standard OAuth2.1 flow. Use the included Postman collection to test endpoints and flows, and leverage the ngrok guidance to expose localhost in environments that require a public URL. The server runs on port 1335 by default and can be configured via environment variables to suit your deployment (see installation notes).

How to install

Prerequisites:

Node.js and npm installed
git (optional, for cloning)

Installation steps:

Clone the repository (or download the source): git clone <repository-url> cd mcp-oauth2.1-server
Install dependencies: npm install
Build the server (transpile TypeScript to JavaScript): npm run build
Start the server: npm run start
- By default the server will listen on port 1335. You can override port and protocol using environment variables (see notes).
Optional: expose locally via ngrok (for public accessibility): ngrok http --domain=<your-ngrok-domain> 1335

Prerequisite notes:

Ensure you have an OAuth2 provider configured (Cognito or Keycloak) per the README guidance.
If you need to test over HTTP, you must configure the PROTOCOL and Port via environment variables since OAuth2.1 discourages http in most setups.

Additional notes

Environment variables and configuration tips:

PORT: Set the port on which the MCP server listens (default 1335).
PROTOCOL: Set to https (recommended) or http if testing locally and you have appropriate certificates.
If you use localhost with ngrok, use the https-ngrok domain you obtain as the public URL for callbacks.
For OAuth2.1 testing, ensure your Cognito or Keycloak setup has the proper redirect URIs and that the mcp:access scope is configured for your resources.
The server supports two providers (Cognito and Keycloak). Configure your provider in the appropriate environment or config file as described in the repository documentation.
If you run into port conflicts, update PORT in your environment and restart the server.