phoenix-oss/open-mcp-auth-proxy-upstream
0
0
Fork 1
mirror of https://github.com/wso2/open-mcp-auth-proxy.git synced 2025-08-17 11:53:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve readme

Browse source
This commit is contained in:
Pavindu Lakshan 2025-08-06 14:50:20 +05:30
parent 2cad797aee
commit b30aa6273c
3 changed files with 108 additions and 236 deletions
Download patch file Download diff file Expand all files Collapse all files

62
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,62 @@
# Contributing
## Build from Source
> Prerequisites
>
> * Go 1.20 or higher
> * Git
> * Make (optional, for simplified builds)
1. **Clone the repository:**
```bash
git clone https://github.com/wso2/open-mcp-auth-proxy
cd open-mcp-auth-proxy
```
2. **Install dependencies:**
```bash
go get -v -t -d ./...
```
3. **Build the application:**
**Option A: Using Make**
```bash
# 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)**
```bash
# 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
```
After building, you'll find the executables in the `build` directory (when using Make) or in your project root (when building manually).
### Additional Make Targets
If you're using Make, these additional targets are available:
```bash
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
```

261
README.md
View file

@ -10,83 +10,38 @@ A lightweight authorization proxy for Model Context Protocol (MCP) servers that
![Architecture Diagram](https://github.com/user-attachments/assets/41cf6723-c488-4860-8640-8fec45006f92)
## 🛡️ 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`<br> No scope or audience enforcement |
| Latest(draft) | Read `MCP-Protocol-Version` from client header<br> SSE handshake returns `WWW-Authenticate: Bearer resource_metadata="…"`<br> `/message` enforces:<br>`aud` claim == `ResourceIdentifier`<br>`scope` claim contains `requiredScope`<br>Scope based access control<br>Rich `WWW-Authenticate` on 401s<br>Serves `/​.well-known/oauth-protected-resource` JSON |
- **Dynamic Authorization**: based on MCP Authorization Specification.
- **JWT Validation**: Validates the token’s signature, checks the `audience` claim, and enforces scope requirements.
- **Identity Provider Integration**: Supports integrating any OAuth/OIDC provider such as Asgardeo, Auth0, Keycloak, etc.
- **Protocol Version Negotiation**: via `MCP-Protocol-Version` header.
- **Flexible Transport Modes**: Supports STDIO, SSE and streamable HTTP transport options.
## 🛠️ 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:
> **Prerequisites**
>
> ```bash
> python3 -m venv .venv
> source .venv/bin/activate
> pip3 install -r requirements.txt
> ```
>
> 3. Start the example server:
>
> ```bash
> python3 echo_server.py
> ```
* An MCP client that supports MCP authorization
### Basic Usage
> * A running MCP server (Use the [example MCP server](resources/README.md) if you don't have an MCP server already)
> * An MCP client that supports MCP authorization specification
1. Download the latest release from [Github releases](https://github.com/wso2/open-mcp-auth-proxy/releases/latest).
2. Start the proxy in demo mode (uses pre-configured authentication with Asgardeo sandbox):
#### Linux/macOS:
- Linux/macOS:
```bash
./openmcpauthproxy --demo
```
#### Windows:
- Windows:
```powershell
.\openmcpauthproxy.exe --demo
```
> The repository comes with a default `config.yaml` file that contains the basic configuration:
>
> ```yaml
> 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](https://github.com/shashimalcse/inspector)(This is a temporary fork with fixes for authentication [issues](https://github.com/modelcontextprotocol/typescript-sdk/issues/257) in the original implementation)
3. Connect using an MCP client like [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
## 🔒 Integrate an Identity Provider
@ -96,10 +51,10 @@ To enable authorization through your Asgardeo organization:
1. [Register](https://asgardeo.io/signup) and create an organization in Asgardeo
2. Create an [M2M application](https://wso2.com/asgardeo/docs/guides/applications/register-machine-to-machine-app/)
1. [Authorize this application](https://wso2.com/asgardeo/docs/guides/applications/register-machine-to-machine-app/#authorize-the-api-resources-for-the-app) to invoke "Application Management API" with the `internal_application_mgt_create` scope
3. [Authorize this application](https://wso2.com/asgardeo/docs/guides/applications/register-machine-to-machine-app/#authorize-the-api-resources-for-the-app) to invoke "Application Management API" with the `internal_application_mgt_create` scope
![image](https://github.com/user-attachments/assets/0bd57cac-1904-48cc-b7aa-0530224bc41a)
3. Update `config.yaml` with the following parameters.
4. Update `config.yaml` with the following parameters.
```yaml
base_url: "http://localhost:8000" # URL of your MCP server
@ -115,7 +70,7 @@ authorization_servers: # Authorization ser
jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks" # JWKS URL
```
4. Start the proxy with Asgardeo integration:
5. Start the proxy with Asgardeo integration:
```bash
./openmcpauthproxy --asgardeo
@ -126,59 +81,24 @@ jwks_uri: "https://api.asgardeo.io/t/acme/oauth2/jwks" # JWKS URL
- [Auth0](docs/integrations/Auth0.md)
- [Keycloak](docs/integrations/keycloak.md)
# ⚙️ Advanced Configuration
## Transport Modes
### 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
### **STDIO Mode**
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:
```bash
./openmcpauthproxy --demo --stdio
```
#### Example: Running an MCP Server as a Subprocess
> **Note**: Any commands specified (like `npx` in the example below) must be installed on your system first
1. Configure stdio mode in your `config.yaml`:
```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"
- "GITHUB_PERSONAL_ACCESS_TOKEN=gitPAT"
```
2. Run the proxy with stdio mode:
@ -187,132 +107,10 @@ demo:
./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
- **SSE Mode (Default)**: For Server-Sent Events transport
- **Streamable HTTP Mode**: For Streamable HTTP transport
### 📝 Complete Configuration Reference
```yaml
# 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
### Prerequisites
* Go 1.20 or higher
* Git
* Make (optional, for simplified builds)
### Clone and Build
1. **Clone the repository:**
```bash
git clone https://github.com/wso2/open-mcp-auth-proxy
cd open-mcp-auth-proxy
```
2. **Install dependencies:**
```bash
go get -v -t -d ./...
```
3. **Build the application:**
**Option A: Using Make**
```bash
# 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)**
```bash
# 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:**
```bash
# If built with Make
./build/linux/openmcpauthproxy --demo
# If built manually
./openmcpauthproxy --demo
```
**Windows:**
```powershell
# If built with Make
.\build\windows\openmcpauthproxy.exe --demo
# If built manually
.\openmcpauthproxy.exe --demo
```
### Available Command Line Options
## Available Command Line Options
```bash
# Start in demo mode (using Asgardeo sandbox)
@ -331,15 +129,6 @@ After building, you'll find the executables in the `build` directory (when using
./openmcpauthproxy --help
```
### Additional Make Targets
## Contributing
If you're using Make, these additional targets are available:
```bash
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
```
We appreciate your contributions, whether it is improving documentation, adding new features, or fixing bugs. To get started, please refer to our [contributing guide](CONTRIBUTING.md).

21
resources/README.md Normal file
View file

@ -0,0 +1,21 @@
# Example MCP server
Use this example MCP server, if you don't already have an MCP server to test the open-mcp-auth-proxy.
## Setting Up
1. Navigate to the `resources` directory
2. Set up a Python environment:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.txt
```
3. Start the example server:
```bash
python3 echo_server.py
```