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):

Linux/macOS:

./openmcpauthproxy --demo

Windows:

.\openmcpauthproxy.exe --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

• Go 1.20 or higher
• Git
• Make (optional, for simplified builds)

Clone and Build

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 the application:

   Option A: Using Make

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

   Option B: Manual build (works on all platforms)

   # Build for your current platform
   go build -o openmcpauthproxy ./cmd/proxy
   
   # Cross-compile for other platforms
   GOOS=linux GOARCH=amd64 go build -o openmcpauthproxy-linux ./cmd/proxy
   GOOS=windows GOARCH=amd64 go build -o openmcpauthproxy.exe ./cmd/proxy
   GOOS=darwin GOARCH=amd64 go build -o openmcpauthproxy-macos ./cmd/proxy

Run the Built Application

After building, you'll find the executables in the build directory (when using Make) or in your project root (when building manually).

Linux/macOS:

# If built with Make
./build/linux/openmcpauthproxy --demo

# If built manually
./openmcpauthproxy --demo

Windows:

# If built with Make
.\build\windows\openmcpauthproxy.exe --demo

# If built manually
.\openmcpauthproxy.exe --demo

Available Command Line Options

# Start in demo mode (using Asgardeo sandbox)
./openmcpauthproxy --demo

# Start with your own Asgardeo organization
./openmcpauthproxy --asgardeo

# Use stdio transport mode instead of SSE
./openmcpauthproxy --demo --stdio

# Enable debug logging
./openmcpauthproxy --demo --debug

# Show all available options
./openmcpauthproxy --help

Additional Make Targets

If you're using Make, these additional targets are available:

make test       # Run tests
make coverage   # Run tests with coverage report
make fmt        # Format code with gofmt
make vet        # Run go vet
make clean      # Clean build artifacts
make help       # Show all available targets