open-mcp-auth-proxy-upstream/README.md

Open MCP Auth Proxy

A lightweight authorization proxy for Model Context Protocol (MCP) servers that enforces authorization according to the MCP authorization specification

🛡️ What it Does?

• Intercept incoming requests
• Validate authorization tokens
• Offload authentication and authorization to OAuth-compliant Identity Providers
• Support the MCP authorization protocol

🚀 Features

• Dynamic Authorization based on MCP Authorization Specification.
• JWT Validation (signature, audience, and scopes).
• Identity Provider Integration (OAuth/OIDC via Asgardeo, Auth0, Keycloak).
• Protocol Version Negotiation via MCP-Protocol-Version header.
• Comprehensive Authentication Feedback via RFC-compliant challenges.
• Flexible Transport Modes: SSE and stdio.

📌 MCP Specification Verions

Version	Behavior
2025-03-26	Only signature check of Bearer JWT on both /sse and /message No scope or audience enforcement
Latest(draft)	Read MCP-Protocol-Version from client header SSE handshake returns WWW-Authenticate: Bearer resource_metadata="…" /message enforces: aud claim == ResourceIdentifier scope claim contains requiredScope Scope based access control Rich WWW-Authenticate on 401s Serves /​.well-known/oauth-protected-resource JSON

🛠️ Quick Start

Prerequisites

• Go 1.20 or higher
• A running MCP server

If you don't have an MCP server, you can use the included example:

1. Navigate to the resources directory
2. Set up a Python environment:

python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt

3. Start the example server:

python3 echo_server.py

• An MCP client that supports MCP authorization

Basic Usage

1. Download the latest release from Github releases.

2. Start the proxy in demo mode (uses pre-configured authentication with Asgardeo sandbox):

./openmcpauthproxy --demo

The repository comes with a default config.yaml file that contains the basic configuration:

listen_port: 8080
base_url: "http://localhost:8000"  # Your MCP server URL
paths:
  sse: "/sse"
  messages: "/messages/"

3. Connect using an MCP client like MCP Inspector(This is a temporary fork with fixes for authentication issues in the original implementation)

🔒 Integrate an Identity Provider

Asgardeo

To enable authorization through your Asgardeo organization:

1. Register and create an organization in Asgardeo

2. Create an M2M application

   1. Authorize this application to invoke "Application Management API" with the internal_application_mgt_create scope

3. Update config.yaml with the following parameters.

base_url: "http://localhost:8000"                              # URL of your MCP server  
listen_port: 8080                                              # Address where the proxy will listen

resource_identifier: "http://localhost:8080"                 # Proxy server URL
scopes_supported:                                            # Scopes required to defined for the MCP server
- "read:tools"
- "read:resources"
audience: "<audience_value>"                                 # Access token audience
authorization_servers:                                       # Authorization server issuer identifier(s)
- "https://api.asgardeo.io/t/acme"
jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks"       # JWKS URL

4. Start the proxy with Asgardeo integration:

./openmcpauthproxy --asgardeo

Other OAuth Providers

• Auth0
• Keycloak

⚙️ Advanced Configuration

Transport Modes

The proxy supports two transport modes:

• SSE Mode (Default): For Server-Sent Events transport
• stdio Mode: For MCP servers that use stdio transport

When using stdio mode, the proxy:

• Starts an MCP server as a subprocess using the command specified in the configuration
• Communicates with the subprocess through standard input/output (stdio)
• Note: Any commands specified (like npx in the example below) must be installed on your system first

To use stdio mode:

./openmcpauthproxy --demo --stdio

Example: Running an MCP Server as a Subprocess

1. Configure stdio mode in your config.yaml:

listen_port: 8080
base_url: "http://localhost:8000" 

stdio:
  enabled: true
  user_command: "npx -y @modelcontextprotocol/server-github"  # Example using a GitHub MCP server
  env:                           # Environment variables (optional)
    - "GITHUB_PERSONAL_ACCESS_TOKEN=gitPAT"

# CORS configuration
cors:
  allowed_origins:
    - "http://localhost:5173"  # Origin of your client application
  allowed_methods:
    - "GET"
    - "POST"
    - "PUT"
    - "DELETE"
  allowed_headers:
    - "Authorization"
    - "Content-Type"
  allow_credentials: true

# Demo configuration for Asgardeo
demo:
  org_name: "openmcpauthdemo"
  client_id: "N0U9e_NNGr9mP_0fPnPfPI0a6twa"
  client_secret: "qFHfiBp5gNGAO9zV4YPnDofBzzfInatfUbHyPZvM0jka"    

2. Run the proxy with stdio mode:

./openmcpauthproxy --demo

The proxy will:

• Start the MCP server as a subprocess using the specified command
• Handle all authorization requirements
• Forward messages between clients and the server

📝 Complete Configuration Reference

# Common configuration
listen_port: 8080
base_url: "http://localhost:8000"
port: 8000

# Path configuration
paths:
  sse: "/sse"
  messages: "/messages/"

# Transport mode
transport_mode: "sse"  # Options: "sse" or "stdio"

# stdio-specific configuration (used only in stdio mode)
stdio:
  enabled: true
  user_command: "npx -y @modelcontextprotocol/server-github"  # Command to start the MCP server (requires npx to be installed)
  work_dir: ""  # Optional working directory for the subprocess

# CORS configuration
cors:
  allowed_origins:
    - "http://localhost:5173"
  allowed_methods:
    - "GET"
    - "POST"
    - "PUT"
    - "DELETE"
  allowed_headers:
    - "Authorization"
    - "Content-Type"
  allow_credentials: true

# Demo configuration for Asgardeo
demo:
  org_name: "openmcpauthdemo"
  client_id: "N0U9e_NNGr9mP_0fPnPfPI0a6twa"
  client_secret: "qFHfiBp5gNGAO9zV4YPnDofBzzfInatfUbHyPZvM0jka"  

# Asgardeo configuration (used with --asgardeo flag)
resource_identifier: "http://localhost:8080"                 
scopes_supported:                                 
- "read:tools"
- "read:resources"
audience: "<audience_value>"
authorization_servers:
- "https://api.asgardeo.io/t/acme"
jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks"   

🖥️ Build from source

git clone https://github.com/wso2/open-mcp-auth-proxy
cd open-mcp-auth-proxy
go get github.com/golang-jwt/jwt/v4 gopkg.in/yaml.v2
go build -o openmcpauthproxy ./cmd/proxy