oauthKeycloakProvider when a Keycloak realm is the authorization server. MCP clients register directly with Keycloak, and mcp-use verifies realm-issued access tokens against the resolved MCP resource.
Prepare Keycloak
Configure Dynamic Client Registration for the hosts used by your MCP clients. Keep redirect URI policies strict, and add browser client origins when browser-based clients require them. For production, only require Initial Access Tokens after confirming that every intended MCP client can send one during registration. The mcp-use provider verifies tokens; it does not perform registration on the client’s behalf.Configure the server
serverUrl and realm are required. They are not read from the environment by the provider.
audience option. Verification is bound to the resolved MCP resource, so configure Keycloak to issue access tokens for that resource.
Use roles and permissions
Realm roles arectx.auth.user.roles. Resource roles are flattened into top-level permissions as resource:role.
realmAccess and resourceAccess objects. Prefer normalized roles and permissions; inspect raw access objects only when the flattened form is insufficient.
Production checks
- Serve both Keycloak and the MCP server over HTTPS.
- Configure token audience/resource claims for the canonical MCP endpoint.
- Restrict DCR according to the capabilities of your MCP clients.
- Decide whether each tool uses realm roles, flattened resource permissions, or both.
Runnable Keycloak example
Compare with the maintained Keycloak example.
Keycloak Client Registration
Configure Dynamic Client Registration.
User Context
Use Keycloak user fields, roles, and permissions.