mirror of
https://github.com/wso2/open-mcp-auth-proxy.git
synced 2025-08-18 04:09:57 +00:00
134 lines
5.2 KiB
Markdown
134 lines
5.2 KiB
Markdown
# 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).
|