Keycloak Realm Inspector
Keycloak Realm Inspector
Un servidor MCP que es puramente un recurso protegido OAuth 2.0, para una charla de KeyConf 2026 sobre Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-02).
No emite nada — ni /authorize, ni /token, ni secreto de cliente. Keycloak emite los tokens; este servidor los valida contra el JWKS de Keycloak, sirve el descubrimiento de la RFC 9728 y expone tres herramientas que hacen visible CIMD desde dentro del servidor de recursos.
Tres partes, deliberadamente separadas
Keycloak | el servidor de autorización. |
El cliente MCP | publica su documento de metadatos en una URL que controla. Esa URL es su |
Este servidor | el recurso protegido. Puerto 9001 |
Este servidor no aloja, lee ni obtiene el documento de metadatos del cliente.
No hay ninguna ruta /client-metadata.json ni copia local. Keycloak obtiene esa URL a través de la red durante /authorize. En este repositorio, la URL solo aparece como una cadena opaca que llega en el claim azp — que es el punto central de la demo, y por eso el documento lo sirve un proceso separado en un puerto separado.
Related MCP server: Akeyless MCP Interop (OpenID AIIM)
Ejecución
Se asume que Keycloak está en marcha, con el realm creado y la política de cliente CIMD ya aplicada. El cliente, su documento de metadatos y el asistente de tokens se encuentran junto a este repositorio en ../cimd-demo/auth-server/.
# terminal 1 — the client's document. Its own party, its own port.
cd ../cimd-demo/auth-server && python -m http.server 9000
# terminal 2 — the resource server
pip install -r requirements.txt
python server.py # http://localhost:9001
# terminal 3 — get a token, then point an MCP client at :9001/mcp
cd ../cimd-demo/auth-server && python get-token.pyEl flujo
El cliente llama a
/mcpsin token y recibe un 401 conWWW-Authenticate: Bearer ..., resource_metadata="…".El cliente sigue esa referencia hasta
/.well-known/oauth-protected-resource/mcpy descubre qué servidor de autorización emite tokens válidos.El cliente se autentica directamente contra Keycloak, usando la URL de su documento de metadatos como
client_id. Keycloak obtiene esa URL y materializa al cliente.El cliente reintenta
/mcpcon el token de portador.
La RFC 9728 §3.1 sitúa el segmento well-known entre el host y la ruta del recurso, por lo que el documento de descubrimiento se encuentra en /.well-known/oauth-protected-resource/mcp. La ruta a secas devuelve un 404.
Herramientas
whoami()—sub,preferred_username,azp,scope,exp,issdel token del llamante, además deregistered_via_cimd. Solo lee el token; no realiza ninguna llamada a Keycloak, por lo que funciona incluso si las credenciales de administrador son incorrectas.list_clients(only_cimd=False)— clientes del realm, con losclient_idcon forma de URL ordenados al principio para que el cliente llamante termine en la primera línea.get_client_metadata(client_id)— la representación propia de Keycloak de un cliente. Esta es la vista derivada de Keycloak, no el documento publicado.
CIMD se detecta porque el client_id empieza por http:// o https://. Un client_id con forma de URL es la pista.
get_client_metadata elimina secret y registrationAccessToken antes de devolverlos. Ambos son credenciales de portador activas, y esta salida va a un proyector y a una grabación.
Dos carencias conocidas
Indicadores de recurso RFC 8707. audience= está presente pero comentado en JWTVerifier. Restringir el token por audiencia requeriría que el cliente enviara resource en /authorize, y la ruta CIMD de Keycloak 26.7 aún no lo respeta (keycloak#45106, keycloak#45284). Por lo tanto, el token lleva la audiencia account habitual de Keycloak y este servidor no puede restringir por audiencia. Visible a propósito.
Sin aplicación de scopes. required_scopes no está definido, por lo que se acepta cualquier token del realm con firma válida y no caducado — incluido uno de una concesión de contraseña de admin-cli. Eso es útil en el escenario: ejecuta whoami() con un token de administrador (azp es una cadena opaca) y de nuevo con el token CIMD (azp es una URL), la misma herramienta, el mismo servidor, la diferencia en un solo campo. También significa que debes estar seguro de qué token tienes en la mano.
Configuración
Todos son os.getenv con valores predeterminados de localhost.
Variable | Valor predeterminado |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
KEYCLOAK_ISSUER y KEYCLOAK_JWKS_URI son configurables por separado en lugar de derivarse el uno del otro: en Kubernetes el emisor es la URL pública, por lo que iss coincide con lo que ven los clientes, mientras que la obtención de JWKS debe dirigirse al Service dentro del clúster.
fastmcp está fijado a una versión exacta. La superficie de autenticación cambia — resource_server_url pasó a ser base_url, AccessToken.claims llegó en la 2.11.3 — y allowed_client_redirect_uris no es un parámetro de RemoteAuthProvider en ninguna versión, a pesar de lo que muestra la documentación. Pertenece a OAuthProxy, que este servidor no usa.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
Remote MCP for A2A caller identity, scope policy, verdict receipts, and audit history.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
OAuth scope approvals and consent receipts for remote MCP servers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceDemonstrates MCP remote authentication boundary with OAuth 2.0, Keycloak token introspection, audience and scope validation, and protected tools.1-
- AlicenseNot gradedqualityDmaintenanceImplements an MCP server with OAuth 2.1 Protected Resource Metadata, enabling token-based authentication for MCP tools like ping.MIT
- AlicenseAqualityBmaintenanceEnables MCP-capable clients to inspect and manage Keycloak realms, users, clients, roles, and groups with layered security modes, realm allowlisting, protected realms, delete gating, dry-run, and audit logging.855 npm1MIT
- FlicenseBqualityBmaintenanceEnables MCP clients to authenticate through OIDC and call protected tools while rejecting unauthenticated requests.26-