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

1.7 KiB Raw Permalink Blame History