keycloak-agent¶
Keycloak Identity and Access Management MCP Server + Agent for the scion-sdk ecosystem — typed, deterministic tools for realms, users, and OIDC clients, plus an optional Pydantic-AI agent server.
Official documentation
This site is the canonical reference for keycloak-agent, maintained alongside
every release.
Overview¶
keycloak-agent wraps the Keycloak Admin REST API with a typed, deterministic MCP
tool surface and ships an optional agent server. It provides:
Api— a dynamic facade (keycloak_agent.api_client.Api) composed of realm, user, and OIDC-client domain modules over the Keycloak Admin REST API.- MCP tools — realm, user, and client operations registered under the
KEYtag, with runtime toolset selection to keep the model's context window lean. - An agent server — an optional Pydantic-AI
keycloak-agentthat consumes the MCP tools for autonomous identity operations.
The server registers read operations that work as soon as the connection is configured; administrative writes ran only when valid credentials are present.
Explore the documentation¶
- :material-rocket-start: Installation — pip, source, extras, and the prebuilt Docker image.
- Deployment — run the MCP server and agent, Docker Compose, Caddy + Technitium.
- Usage — the MCP tools, the
Apiclient, and the CLI. - Backing Platform — deploy Keycloak with Docker.
- Architecture — the dynamic facade and tool surface.
- Concepts — the
CONCEPT:KEY-*registry.
Quick start¶
Connect it to a Keycloak server:
export KEYCLOAK_URL=<configured-endpoint>
export KEYCLOAK_AGENT_USERNAME=<configured-principal>
export KEYCLOAK_AGENT_PASSWORD=<runtime-secret>
export KEYCLOAK_REALM=master
keycloak-mcp --transport streamable-http --host 0.0.0.0 --port 8000
See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).
Spec delivery¶
Spec delivery dashboard. No owned specs are recorded yet. Missing requirement and code mappings remain unknown.