What is Mcp Auth Example

mcp-auth-example is a reference implementation that demonstrates how to integrate OAuth 2.0 authorization into the Model Context Protocol (MCP). It aims to identify the challenges of building such an integration.

Use cases

Use cases include integrating OAuth 2.0 authorization in applications that utilize MCP, managing access to protected resources, and demonstrating OAuth metadata discovery for clients.

How to use

To use mcp-auth-example, set up the MCP-style resource server and the Dex identity provider and authorization server. Access the OAuth metadata at ‘/.well-known/oauth-protected-resource’ and use cookie-based authentication for the protected SSE endpoint.

Key features

Key features include a split architecture for resource and authorization servers, exposure of OAuth metadata, and a protected SSE endpoint using cookie-based authentication.

Where to use

mcp-auth-example can be used in applications that require secure resource access and authorization management, particularly in environments leveraging the Model Context Protocol.

OAuth Discovery Demo for Model Context Protocol (MCP)

This repo is a cobbled together reference implementation demonstrating how OAuth 2.0 authorization can be integrated into the Model Context Protocol (MCP) using Aaron Parecki’s suggestions on OAuth for MCP. The intent was to understand what the pain points are in actually building it.

🔍 Overview

This demo shows how an MCP-compatible resource server can expose OAuth metadata using /.well-known/oauth-protected-resource, allowing clients to discover the appropriate authorization server without assuming the MCP server handles both authentication and authorization.

It mirrors the architecture and intent of Aaron Parecki’s blog post, but tries to adapat it into a working local environment.

⚙️ What’s Included

• resource-server/: MCP-style server that:
  • Exposes /.well-known/oauth-protected-resource
  • Serves a protected SSE endpoint using cookie-based auth
• busybox server: A separate server that statically serves /.well-known/oauth-authorization-server metadata
• dex idp and auth server: Dex is being used both as an idp and authorization server

🧩 Notes & Limitations

• ✅ Split RS/AS: As recommended in the blog post, the resource server and authorization server are completely separate processes.
• ❌ No custom headers over SSE: Due to limitations of the EventSource spec, custom headers (e.g., Authorization) are not supported in SSE requests. Cookie-based auth is required.
• ⚠️ SSE & HTTP Headers: HTTP Headers cannot be set after the initial handshake for SSE .
• ⚠️ MCP SDKs have poor DX: This implementation was built manually because current MCP SDKs (as of April 2025) are missing features and are very awkward to use

📖 Background & Credits

This work is directly inspired by Aaron Parecki’s excellent post:

Let’s Fix OAuth in MCP – Aaron Parecki, April 3, 2025

If you’re thinking about how to structure OAuth in MCP systems, read it.

🚀 Running It

1. Install Docker

   # Install Docker according to your OS: https://docs.docker.com/get-docker/
   

2. Start the Authentication Server

   # Start the Dex server and related services
   docker-compose up
   

3. Start the MCP Server

   # Install dependencies and start the server
   cd mcp-server && npm install && npm run dev
   

4. Start the MCP Client

   # In a new terminal, install dependencies and start the client -- this will execute the auth flow immediately
   cd mcp-client && npm install && npm run dev
   

🖼️ Demo Flow Screenshots

1. MCP Server Logs

The server initializes, registers tools, and validates tokens using JWT.

2. MCP Client Starting OAuth Flow

The client detects auth is required and begins the OAuth discovery flow sequence.

3. Browser Redirect to Dex Login

The user is redirected to Dex for authentication.

4. Authentication Success

After successful login, the authorization code is returned to the client.

After this flow completes, the MCP client communicates securely with the MCP server using the obtained access token.