Keycloak Authentication Example

This example demonstrates how to configure MXCP with Keycloak authentication.

Prerequisites

A running Keycloak server (see quick start below)
MXCP installed (pip install mxcp)

Quick Start with Docker

Run Keycloak using Docker:

docker run -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Keycloak Setup

Access the admin console at http://localhost:8080/admin
Login with username: admin, password: admin
Create a new realm (or use the default master realm)
Create a new client:
- Client ID: mxcp-demo
- Client authentication: ON
- Valid redirect URIs: http://localhost:8000/*
Copy the client secret from the Credentials tab

Configuration

Set environment variables:

export KEYCLOAK_CLIENT_ID="mxcp-demo"
export KEYCLOAK_CLIENT_SECRET="your-client-secret"
export KEYCLOAK_REALM="master"  # or your custom realm
export KEYCLOAK_SERVER_URL="http://localhost:8080"

Running the Example

Start the MXCP server:

cd examples/keycloak
mxcp serve --debug

In another terminal, connect with the MCP client:
```
mcp connect http://localhost:8000
```
You'll be redirected to Keycloak for authentication

Testing Tools

Once authenticated, try running these example tools:

# Get current user info
mcp run tool get_user_info

# Query data with user context
mcp run resource user_data

Production Considerations

Use HTTPS for all URLs in production
Configure proper redirect URIs
Set up appropriate Keycloak realm roles and permissions
Enable refresh token rotation
Configure session timeouts