Skip to main content
Use 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.
There is no Keycloak 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 are ctx.auth.user.roles. Resource roles are flattened into top-level permissions as resource:role.
The mapped user also includes optional profile fields and the raw 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.