Keycloak MCP server

Cloud-IAM can run a Model Context Protocol server next to your managed Keycloak. Once enabled, an MCP-aware assistant such as Claude or Cursor can explore your realms, users, clients, groups and events by talking to the Keycloak Admin REST API on your behalf.

Read-only for now

The Keycloak MCP server only exposes read operations. No tool creates, updates or deletes anything in your Keycloak. Write operations are not supported yet.

Not the same thing as the Cloud-IAM MCP

Cloud-IAM ships two MCP servers, and they answer different questions:

	Cloud-IAM MCP	Keycloak MCP (this page)
Hosted at	https://mcp.cloud-iam.com/mcp	your own deployment's hostname
Talks to	the Cloud-IAM control plane	your Keycloak Admin API
Answers	"list my deployments", "what's my billing?"	"list the users of realm acme"
Enabled from	Settings → MCP (organization)	Configuration → Keycloak MCP (deployment)

They are independent, so you can enable either one, both, or neither.

Prerequisites

Three conditions must be met before you can turn the feature on.

Requirement	Detail
Keycloak version	The deployment must run Keycloak 26.6 or later. The MCP gateway relies on Standard Token Exchange v2, which only exists from that version.
Plan	The feature is available on the Premium support level and above.
Permission	You need the Edit deployment general configuration permission on the deployment.

If your deployment runs an older Keycloak, use the upgrade on demand flow first.

How to enable the Keycloak MCP server

1. Open the Cloud-IAM console and select your deployment.
2. Go to Configuration in the side menu.
3. Open the Keycloak MCP tab.
4. Toggle Enable Keycloak MCP server on.

The console confirms with Keycloak MCP server setting updated., and the card then tells you that the Keycloak clients have been provisioned and that the deployment is being updated to bring the MCP stack online.

What happens when you enable it

Two things happen, in this order.

First, Cloud-IAM provisions three OAuth clients in the master realm of your Keycloak:

Client	Type	Role
sa_cloud-iam-mcp-login	Public (PKCE)	Signs in the end user from the MCP client.
sa_cloud-iam-mcp-gateway	Confidential	Exchanges the user token for an on-behalf-of token.
sa_cloud-iam-mcp-server	Confidential	Service-account fallback, unused in the default setup.

Then the deployment is redeployed to bring the MCP stack online. Expect the usual redeployment delay before the connection URL starts answering.

These clients belong to Cloud-IAM

Don't rename, delete or repurpose the three sa_cloud-iam-mcp-* clients. They are re-created and reconciled every time the feature is enabled, so manual edits are overwritten. The only change you may need to make yourself is adding a redirect URI.

Cloud-IAM never stores the client secrets and never displays them in the console. Keycloak is the only place they exist.

How to retrieve the connection URL

Once the feature is enabled, the card displays a Connection URL field with a copy button. The URL is your deployment hostname followed by /mcp:

https://<your-deployment-hostname>/mcp

For a deployment whose Keycloak lives at https://keycloak.acme.com/auth, the MCP URL is https://keycloak.acme.com/mcp.

The gateway also publishes the standard discovery documents, which most MCP clients resolve on their own:

• https://<your-deployment-hostname>/.well-known/oauth-protected-resource
• https://<your-deployment-hostname>/.well-known/oauth-authorization-server
• https://<your-deployment-hostname>/.well-known/openid-configuration

How to grant access to your users

Enabling the server is not enough: a user also needs the right roles inside Keycloak. Sign-in happens on the master realm, since that is where the MCP clients live.

Access is checked twice, and a user has to pass both checks.

The gateway runs the first check, on the caller's realm roles on the master realm. One of these three roles is required:

• mcp-keycloak-reader
• realm-admin
• admin

Keycloak runs the second check itself, on the caller's realm-management client roles, exactly as it would in the admin console. A user without view-users cannot list users through MCP either.

The simplest starting point

A master-realm account with the admin role passes both checks on every realm of the deployment, with no extra setup. Start there to confirm the connection works, then narrow the permissions down.

To give someone read access without making them a full administrator, create a realm role named mcp-keycloak-reader in the master realm, assign it to the user, then grant the realm-management roles matching the tools you want them to use. Cloud-IAM does not create the mcp-keycloak-reader role for you. Defining it yourself is what keeps you in control of who reaches the Admin API.

How to connect an MCP client

The connection is a regular OAuth 2.1 sign-in. You do not generate an API key and you do not paste a secret anywhere: the user signs in with their own Keycloak account, and the assistant receives a token scoped to that user.

Claude (web and desktop)

The sa_cloud-iam-mcp-login client already knows Claude's callback URL, so there is nothing else to set up.

1. In Claude, go to Settings → Connectors → Add custom connector.
2. Give it a name, for example Keycloak production.
3. Paste your connection URL: https://<your-deployment-hostname>/mcp.
4. Click Add and complete the sign-in that opens in your browser.

Other MCP clients

Any client that speaks HTTP transport with OAuth 2.1 works the same way, with one caveat.

Clients that sign in through a local callback, such as Claude Code, Cursor and most desktop tools, use a http://localhost:<port>/... redirect URI. That URI is not registered on sa_cloud-iam-mcp-login by default, so Keycloak rejects the sign-in with Invalid parameter: redirect_uri.

To use one of these clients, add its redirect URI to the sa_cloud-iam-mcp-login client in your master realm:

1. Open your Keycloak admin console on the master realm.
2. Go to Clients → sa_cloud-iam-mcp-login → Settings.
3. Add the client's callback URL to Valid redirect URIs.
4. Save, then retry the connection.

For clients configured through a JSON file, the entry is typically:

{
  "mcpServers": {
    "keycloak": {
      "url": "https://<your-deployment-hostname>/mcp"
    }
  }
}

Available tools

Every tool is a read-only call on the Keycloak Admin REST API. The realm is a tool parameter rather than part of the URL, so a single connection serves every realm the caller is allowed to administer.

The realm parameter is required everywhere except keycloak_list_realms. Parameters in italics are optional.

Realms

Tool	Parameters	Description
keycloak_list_realms	none	List the realms visible to the caller.
keycloak_get_realm	realm	Get the configuration of a single realm.

Users

Tool	Parameters	Description
keycloak_list_users	realm, search, first, max	List users, optionally filtered by a free-text search over username, email and name.
keycloak_count_users	realm, search, username, email	Count users, useful before listing or for reporting.
keycloak_get_user	realm, user_id	Get a single user by UUID.
keycloak_get_user_groups	realm, user_id	List the groups a user belongs to.
keycloak_get_user_role_mappings	realm, user_id	Get a user's realm-level and per-client role mappings.
keycloak_list_user_sessions	realm, user_id	List a user's active sessions, with start time, last access, IP address and clients.

Clients and roles

Tool	Parameters	Description
keycloak_list_clients	realm	List the OAuth and OIDC clients of a realm.
keycloak_get_client	realm, client_uuid	Get a single client by UUID, not by its human-readable clientId.
keycloak_list_roles	realm	List the realm roles.

Groups

Tool	Parameters	Description
keycloak_list_groups	realm	List the top-level groups.
keycloak_get_group	realm, group_id	Get a group by UUID, with its attributes and directly-assigned roles.
keycloak_list_group_members	realm, group_id, first, max	List the direct members of a group.
keycloak_list_subgroups	realm, group_id, first, max	List the direct child groups of a group.

Federation and identity providers

Tool	Parameters	Description
keycloak_list_identity_providers	realm	List the SAML, OIDC and social identity providers.
keycloak_get_identity_provider	realm, alias	Get a single identity provider by alias.
keycloak_list_components	realm, component_type, parent	List realm components, mainly LDAP and Active Directory user federation providers.

Both identity-provider tools redact provider secrets such as clientSecret from their responses.

Events

Tool	Parameters	Description
keycloak_list_login_events	realm, event_type, client, user, date_from, date_to, first, max	List login and authentication events.
keycloak_list_admin_events	realm, operation_types, resource_types, date_from, date_to, first, max	List administrative events, meaning configuration changes.

Both event tools read the realm's native event log, so they only return data if event logging is enabled on that realm.

How to disable the Keycloak MCP server

Toggle Enable Keycloak MCP server off in the same tab. Cloud-IAM removes the three sa_cloud-iam-mcp-* clients from the master realm and redeploys to tear the MCP stack down.

Disabling always succeeds, even if your Keycloak is temporarily unreachable. The three clients may then be left behind as orphans. They are unusable without the gateway, and re-enabling the feature later reconciles them.

Troubleshooting

The Keycloak MCP tab shows an upgrade prompt

Your deployment runs a Keycloak version older than 26.6. Use upgrade on demand to move to a supported version, then enable the feature.

Keycloak MCP server are not available on your plan

The feature requires the Premium support level or above. Contact support@cloud-iam.com to upgrade your subscription.

The toggle is greyed out with a "You are not allowed" tooltip

Your role on the deployment does not include Edit deployment general configuration. Ask a deployment administrator to enable the feature, or to grant you the permission.

Could not update the Keycloak MCP server

Cloud-IAM could not reach your Keycloak, or its administration account was refused, so the clients could not be provisioned. Check that the deployment is running and stable, then retry. The toggle stays off in that case, so the feature is never reported as enabled when provisioning failed.

Invalid parameter: redirect_uri during sign-in

Your MCP client uses a callback URL that is not registered on sa_cloud-iam-mcp-login. Add it to the client's Valid redirect URIs, as described in Other MCP clients.

The assistant is connected but every tool is denied

The account you signed in with holds none of mcp-keycloak-reader, realm-admin or admin on the master realm. See How to grant access to your users.

A tool returns a 403 from Keycloak

You passed the gateway check, but your realm-management roles do not allow that specific read on that realm. Grant the matching role, for example view-users to list users or view-events to read the event log.

Related pages

• Keycloak MCP technical reference, for the architecture and the identity model behind the feature.
• MCP for the Cloud-IAM console, the control-plane MCP server hosted by Cloud-IAM.
• Keycloak Upgrades Guide, if you need to reach Keycloak 26.6.

Need help with MCP?

If you have any questions or need assistance, submit a ticket through the Ticket Center and our support team will guide you through the process.