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

Open MCP Auth Proxy sits between MCP clients and your MCP server to:

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

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)

Connect 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

asgardeo:                                     
  org_name: "<org_name>"                      # Your Asgardeo org name
  client_id: "<client_id>"                    # Client ID of the M2M app
  client_secret: "<client_secret>"            # Client secret of the M2M app

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)
asgardeo:
  org_name: "<org_name>"
  client_id: "<client_id>"
  client_secret: "<client_secret>"

Build from Source

Prerequisites for Building

• Go 1.20 or higher
• Git
• Make (for Linux/macOS builds)

Building on Linux/macOS

1. Clone the repository:

   git clone https://github.com/wso2/open-mcp-auth-proxy
   cd open-mcp-auth-proxy
   

2. Install dependencies:

   go get -v -t -d ./...
   

3. Build for your platform:

   # Build for all platforms
   make all
   
   # Or build for a specific platform
   make build-linux   # For Linux
   make build-darwin  # For macOS
   make build-linux-arm # For ARM-based Linux
   make build-windows # For Windows
   

4. Find your build in the build directory:

   # For Linux
   ./build/linux/openmcpauthproxy --demo
   
   # For macOS
   ./build/darwin/openmcpauthproxy --demo
   

Building on Windows

1. Clone the repository:

   git clone https://github.com/wso2/open-mcp-auth-proxy
   cd open-mcp-auth-proxy
   

2. Install dependencies:

   go get -v -t -d ./...
   

3. Option 1: Build using Make if you have it installed:

   make build-windows
   

   Option 2: Build manually without Make:

   mkdir -p build\windows
   go build -o build\windows\openmcpauthproxy.exe .\cmd\proxy
   copy config.yaml build\windows\
   

4. Run the built application:

   cd build\windows
   .\openmcpauthproxy.exe --demo
   

Starting the Proxy on Windows

1. Open Command Prompt or PowerShell

2. Navigate to the build directory:

   cd build\windows
   

3. Run the executable with your desired options:

   # Start in demo mode (using Asgardeo sandbox)
   openmcpauthproxy.exe --demo
   
   # Start with Asgardeo integration
   openmcpauthproxy.exe --asgardeo
   
   # Start in stdio mode
   openmcpauthproxy.exe --demo --stdio
   
   # Enable debug logging
   openmcpauthproxy.exe --demo --debug
   
   # See all available options
   openmcpauthproxy.exe --help
   

4. The proxy will start and display messages indicating it's running

5. To stop the proxy, press Ctrl+C in the command window