Content
# Open MCP Auth Proxy
A lightweight authorization proxy for Model Context Protocol (MCP) servers that enforces authorization according to the [MCP authorization specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/)
<a href="">[](https://github.com/wso2/open-mcp-auth-proxy/actions/workflows/release.yml)</a>
<a href="">[](https://stackoverflow.com/questions/tagged/wso2is)</a>
<a href="">[](https://discord.gg/wso2)</a>
<a href="">[](https://twitter.com/intent/follow?screen_name=wso2)</a>
<a href="">[](https://github.com/wso2/product-is/blob/master/LICENSE)</a>
## 🚀 Features
- **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**
>
> * 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:
```bash
./openmcpauthproxy --demo
```
- Windows:
```powershell
.\openmcpauthproxy.exe --demo
```
3. Connect using an MCP client like [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
## 🔒 Integrate an Identity Provider
### Asgardeo
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/)
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
4. Update `config.yaml` with the following parameters.
```yaml
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
```
5. Start the proxy with Asgardeo integration:
```bash
./openmcpauthproxy --asgardeo
```
### Other OAuth Providers
- [Auth0](docs/integrations/Auth0.md)
- [Keycloak](docs/integrations/keycloak.md)
## Transport Modes
### **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
1. Configure stdio mode in your `config.yaml`:
```yaml
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"
```
2. Run the proxy with stdio mode:
```bash
./openmcpauthproxy --demo
```
- **SSE Mode (Default)**: For Server-Sent Events transport
- **Streamable HTTP Mode**: For Streamable HTTP transport
## Available Command Line Options
```bash
# 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
```
## Contributing
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).
