Keycloak MCP authorization server setup

Why teams put a Keycloak MCP authorization server in front of AI agents

Keycloak can act as the OAuth 2.0 and OpenID Connect authorization layer in front of a Model Context Protocol (MCP) server, so that users and AI agents obtain scoped tokens before they reach internal tools or data. Confirm the MCP features your target Keycloak version supports before you commit to this design. The protocol support Keycloak documents covers OpenID Connect, OAuth 2.0 and SAML 2.0 in general. It does not, on its own, show how each MCP specification revision maps to Keycloak behavior, so details such as supported revisions, metadata discovery and client registration must be checked against the current Keycloak documentation and tested in your own environment.

This pattern fits best when identity already lives in Keycloak. Teams that run Keycloak realms for application sign-in can reuse existing users, groups, roles and client configuration, and keep token issuance inside infrastructure they operate. It also fits when access must be decided for each tool or each data set, because network placement alone cannot express that level of control. Organizations that want self-hosted identity for AI tooling, with the same audit and administration model they already use for other applications, usually find the reuse the strongest argument.

The fit is weaker in several cases. If every MCP server is a public SaaS connector that already handles delegated access well, a second authorization layer adds work without much gain. The same is true when no one on the team operates Keycloak, or when the agent platform requires an identity provider that cannot be federated into Keycloak cleanly. Keycloak also becomes one more identity service to patch, back up and make highly available. Before deciding, identify the high availability architecture and production database you would run, since an identity outage stops every agent that depends on it.

Start with three checks. First, list each MCP server and the tools it exposes, and decide which roles or groups may call each one. Second, decide whether agents authenticate as their own clients, act for a signed-in user, or both, because the token contents and audience differ between those patterns. Third, confirm that your chosen Keycloak release documents the MCP metadata and resource indicator behavior you depend on, and that any experimental feature you would need to enable is acceptable under your change control. Fine-grained authorization services are covered separately, so the question here is whether each token carries enough information for every MCP server to make its own decision.

Configuration choices for MCP clients and resource servers

This table compares the decisions that shape how MCP clients register, authenticate and receive tokens, and how MCP servers validate them. Read each row for when the option fits and what to confirm in the Keycloak release and feature set you plan to run. The main takeaway is that registration method, audience mapping and validation style should be settled together, because each one changes what an MCP server can trust.

Decision	Option	When it fits	What to confirm
Pre-registered clients	Client created in advance through realm import, the admin console or the admin API	A known, fixed set of MCP clients that your team controls	Who may create and change clients, and whether client definitions are managed as code
Dynamic client registration	Client registers itself at runtime through the registration endpoint	Many or unknown clients that must onboard without manual steps	Whether anonymous or initial access registration is enabled, and which redirect URI and scope rules apply
Client ID metadata documents	Client identifies itself with a metadata document hosted at a URL	Clients that publish their own metadata and you want to avoid registering each one	Whether this feature is available and enabled in your release and feature set, and how documents are fetched and trusted
Public clients	No client secret; the client relies on PKCE	Browser-based or desktop MCP clients that cannot store a secret safely	PKCE enforcement settings in client policies for your release
Confidential clients	Client authenticates with a secret or another supported client authentication method	Server-side agents or gateways that can store credentials securely	Supported client authentication methods, secret rotation steps and the owner of each credential
Resource indicators	Client sends the resource parameter and Keycloak uses it to scope the token	MCP servers need tokens issued for a specific resource	Whether your release accepts the resource parameter and how it is matched to registered resources
Audience mapping	Protocol mapper or client scope adds the resource value to the access token audience	Resource servers that check the aud claim before serving a request	Mapper types available in your release and whether one token can carry several audiences
Token validation at MCP servers	Local JWT validation against realm keys, or token introspection	Local validation for lower latency; introspection when revocation must be checked on each call	Signing algorithms, key rotation behavior and access to the introspection endpoint in your release

How a Keycloak token reaches an MCP server

The token path has three steps, and each one needs its own test. An MCP client, whether an agent, an IDE or an application, first obtains an access token from a realm in Keycloak. It then presents that token to the MCP server with each request. The MCP server acts as the resource server, so before it runs any tool it must validate the token's issuer, audience, expiry and scopes. Keycloak issues the token, but the MCP server makes the access decision. A token that Keycloak signs correctly can still be rejected by the server, so plan the server's validation logic as separate work from the Keycloak configuration. Confirm which claims your server reads and how it maps scopes to individual tools.

The audience check is the control that prevents a token from being replayed against another service. A token issued for a different API in the same realm may pass signature and expiry checks, so the MCP server must reject any token whose audience does not identify it. Resource indicators, the mechanism by which a client asks for a token bound to a specific resource, are central to this design. Confirm in your Keycloak version and your MCP client how the audience value is requested, and whether an audience mapper is added to tokens by default. Test the server with a token issued for a different service. The server should refuse it, and the refusal should appear in your logs.

Four Keycloak objects shape this path. The realm is the boundary that holds users, clients and signing keys, so decide whether MCP clients share a realm with workforce sign-in or sit in a separate one under your policy. The admin console is where administrators register clients, set the scopes each client may request and review the client scopes. Client scopes bundle the scopes and claims that go into tokens, and they are usually where scopes that correspond to MCP tools are defined. Naming these scopes is therefore part of your authorization design, not an afterthought. Record the exact client, scope and mapper names in your build documentation so that later changes can be traced to a specific object.

Do not assume that every MCP client behaves the same way. Clients differ in how they discover the authorization server, which parameters they send when requesting a token, whether they request resource indicators, how they refresh tokens and how they respond to a rejected token. Test each client you intend to support from end to end. Obtain a token, call a read-only tool, call a tool that requires a narrower scope, and confirm that the server denies calls outside the granted scopes. Also test expiry, refresh and the handling of a token issued to a different client. Keep the results with the client version, because a client update can change its behavior.

Setting up a Keycloak MCP authorization server step by step

This sequence takes a Keycloak instance from a confirmed release and production-grade deployment to an MCP client that receives tokens bound to the MCP server as their audience. Each step closes with a check you can run yourself, so problems surface before the MCP server trusts a single token.

Confirm the release and component versions
Record the Keycloak release you will run, the MCP specification version your client and server implement, and the versions of the MCP SDKs in use. The current Keycloak release is 26.8.1, published October 13, 2026, so confirm whether your organization targets it or an earlier 26.x release before you install. Read the upgrade notes for the target release, including the 26.8 changes to SMTP StartTLS and backchannel logout token validation. The step is done when these versions sit in a written compatibility table that the platform, security and MCP teams have all reviewed.
Deploy Keycloak behind TLS and a reverse proxy
Platform engineers deploy Keycloak following the production guidance: TLS on all communication, a reverse proxy with path restrictions, and the admin console and Administration REST API served on a hostname or context path separate from public frontend URLs. Use a supported production database, such as PostgreSQL in the 14 to 18 range, and keep the development file database out of this environment. Decide how the cluster will provide high availability, since the supported designs need a synchronously replicated database. Check that the admin paths are unreachable from outside your network, and that the public issuer URL serves the OpenID discovery document over HTTPS with a valid certificate chain.
Create a dedicated realm and client set
Identity administrators create a separate realm, or a clearly named set of clients in an existing realm, so MCP access policy, signing keys, sessions and user populations stay apart from workforce application sign-in. Register one client for each MCP client type in your design, for example a confidential client for server-side agents and a public client for interactive tools that cannot keep a secret. Record the redirect URI patterns exactly as the MCP clients will send them. Keep the client definitions in version-controlled configuration so every change is reviewable. The step is complete when the client inventory matches the design document and each client's grant types and redirect URIs match what its MCP client requires.
Enable only confirmed experimental features
Before you enable anything, read the Keycloak documentation for your target release to confirm which MCP-related features exist, which are experimental, and which feature flags turn them on. If your design depends on client ID metadata documents or resource indicators, confirm in that documentation whether your release supports them and how to enable them. Enable only the flags you have confirmed, first in a non-production instance, and record each flag with its reason and owner. Keycloak has said breaking changes in a minor release will be opt-in, so check the upgrade notes for any flag that changes defaults. The step is done when the running instance reports the feature set you recorded and nothing else.
Map audience and scopes to the MCP resource
Configure each MCP client so its tokens carry the MCP server as the audience, using an audience mapper or resource indicator handling, whichever your release supports. Define client scopes that name the MCP server's permissions, and assign each scope only to the clients that need it. Keep user-facing and machine-facing scopes in separate definitions. Decode a test access token in a non-production environment and confirm that the aud claim contains the MCP resource identifier and that the scope claim lists only the intended permissions. Never paste production tokens into an online decoder. Then request a token meant for a different resource and confirm it does not carry the MCP audience.
Wire token validation into the MCP server
The MCP server's developers configure it to validate every incoming access token: the signature is checked against the realm's published keys, the issuer must match the exact issuer URL, expiry and not-before times are enforced, and the audience must equal the server's own resource identifier. Load keys from the discovery document and JWKS endpoint so key rotation does not require a code change. Treat a token with no audience claim as invalid. The step is done when a valid token for the MCP resource succeeds, and a token with a wrong audience, a wrong issuer or an expired lifetime returns an authorization error in each case.
Test end to end with a live MCP client
Connect an MCP client your team uses day to day to the server and complete the full sign-in flow. Call one tool with a scope the user holds, then call a tool that requires a scope the user lacks. The client should obtain a token, the server should accept the permitted call, and the server should deny the restricted call with a clear authorization error. Repeat the token-for-another-resource test from the audience step against the live server. Record the Keycloak release, client versions and configuration commit used for the run. Keep this test as a regression check for future Keycloak upgrades.

Security considerations for agent-to-tool access

An AI agent that calls an MCP server holds a token that can reach tools and data on behalf of your organization. The cards below cover the access risks that Keycloak configuration controls directly, along with the 26.8 upgrade changes and experimental features that affect how the server is run.

Over-broad scopes for agents

Agents often request more scopes than a task needs, and one broad token can then call every tool behind an MCP server. Define client scopes per MCP server and per tool category, and assign them only to the clients that need them. Review the scope mappings on each agent client and confirm that refresh tokens carry no more access than the agent's current task requires. Test each scope with a token the agent should be unable to use.

Audience confusion between MCP servers

A token issued for one MCP server can be presented to another if the receiving server does not check the audience it names. Use resource indicators so that clients request tokens bound to a specific MCP server, and confirm that your Keycloak version and client settings support this as the MCP guidance expects. Each MCP server should validate the audience claim and reject tokens meant for other resources. Test by sending a token issued for server A to server B and confirming the request fails.

Unvetted client registration

Agents and MCP clients may register themselves through dynamic client registration or client ID metadata documents, which can place new clients in front of your realm without a review step. Decide which registration paths are open, who approves a new client, and which redirect URIs and scopes a self-registered client may request. Review the client list on a schedule and remove clients that no team owns.

Admin console and Admin REST API exposure

The admin console and the Administration REST API should not share a public hostname with user-facing frontend URLs. Keycloak's production guide recommends a separate hostname or context path for them, and a reverse proxy with path restrictions should block admin paths on the public listener. Confirm that administrative access comes only from networks you manage, and that the admin hostname is reachable only over TLS.

TLS on all communication

Keycloak's production guide calls for TLS on all communication. Authorization codes, access tokens and client secrets pass through the reverse proxy, the database connection, the management interface and any MCP server that calls token or introspection endpoints, so each hop needs encryption. Verify certificate chains, supported protocol versions and the certificate renewal process for every hop, and record which connections your team has not yet tested.

Upgrade notes and experimental features

The 26.8 upgrade notes enforce SMTP StartTLS without plaintext fallback, so mail relays that offer only plaintext will stop delivering notices. They also require signature validation of backchannel logout tokens from external providers, which can break logout for brokered identity providers that do not sign them. Before enabling any experimental feature, review its security posture and confirm it is intended for production use.

Experimental features and version choices for MCP

For most production MCP authorization deployments, the first decision is to run a stable Keycloak release and build only on features the project treats as supported. The current release is 26.8.1, published October 13, 2026. Supported features carry the project's normal compatibility expectations, which makes them the safer foundation for a server that controls which AI agents can reach your tools and data.

Pin the exact release. Record the full version, such as 26.8.1, in deployment manifests and change records so every environment runs the same build.
Confirm MCP support status. Check the release documentation for each MCP-related capability you plan to use and note whether it is supported or experimental.
Limit custom code to documented extension points. Custom providers and scripts can break when internals change, so keep them small and covered by tests.
Confirm the release line with your support provider. If a distributor or partner supplies support, verify that its release cadence matches your upgrade plans.

Before you rely on any MCP-related capability, confirm its status in the release notes for the exact version you run.

Running the MCP authorization path in production

The database and high availability design are the first production decisions for the MCP authorization path, because every token issued to an MCP client depends on them. Keycloak's supported production databases are MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL (versions 14 to 18), EnterpriseDB Advanced, Amazon Aurora PostgreSQL and Azure SQL. The default dev-file database is for development only, so it should never back a shared authorization server. Choose the supported database your team can back up, restore and patch on its own schedule. Then choose the topology. Keycloak documents a single cluster that can span availability zones and a multi-cluster design (v2) that does not use an external Infinispan cluster. Both require a synchronously replicated database. The deprecated multi-cluster v1 design, which used a separate Infinispan cluster per site, should not be the starting point for a new build. Confirm the replication and failover behavior of your chosen database with its vendor before you commit to a design.

Most teams running Keycloak on Kubernetes will use the Keycloak Operator. Keycloak documents installation through Operator Lifecycle Manager (the recommended method), through kubectl, or through an experimental Helm chart. Set operator updates to manual approval. The Keycloak Operator documentation strongly recommends this mode to avoid unintended automatic upgrades. With manual approval, every Operator or Keycloak version change passes through your change process and a test realm that mirrors the MCP client and resource server settings before it reaches production. Keep the Keycloak and client custom resources in version control so reviewers can see configuration changes, including redirect URIs and client settings used by MCP clients, before they are applied. Ask your platform team who approves each change and how a rollback is performed.

Schema migration is the next decision. Keycloak migrates its database schema automatically at startup by default. It also supports manual migration, where administrators apply the SQL themselves, and the upgrading guide suggests manual migration for large deployments. For the MCP path, a failed automatic migration during startup can stop token issuance for every client, not only MCP clients. Decide which mode fits your database size and change windows, then rehearse the chosen method against a copy of production data before each minor release. Since Keycloak 26.0, the project plans four minor releases a year, so this rehearsal is recurring work and belongs in your operating budget. The Keycloak 26.8 upgrade notes also state that login failures are persisted to the database by default, so ask your database team to size storage and retention for that growth before go-live.

Keycloak exposes Prometheus-format metrics at /metrics on its management interface when it starts with --metrics-enabled=true. Optional HTTP request and cache histograms can be enabled as well. Keep the management interface off the public frontend hostname, consistent with the production guidance to separate administrative and management paths from public URLs. For MCP traffic, monitor token issuance rates, token endpoint error responses and the failed validations reported by your resource servers, and alert on sudden changes from baseline. Confirm with your own tests which metrics cover each MCP flow, including the token requests made by MCP clients and the validation failures seen by MCP servers. Do not assume the standard metrics separate MCP clients from other clients until you have verified the labels in your environment. Record the result as a runbook entry so on-call engineers know which dashboards and alerts apply to the authorization path.

What to confirm before committing to this design

These checks decide whether Keycloak can serve as the authorization server for your MCP servers. Each card covers one item that the Keycloak documentation, your MCP client vendors and your own test results can settle. Confirm them before you commit, because the answers set the release, the configuration and the client changes that follow.

MCP protocol version support

Identify which MCP specification versions your MCP servers and clients implement, then check which Keycloak release and client libraries support the authorization behavior those versions require. The current Keycloak release is 26.8.1, but the release that fits your design may be an earlier one, so match the release to your target MCP version rather than assuming the newest. Confirm the mapping in the Keycloak documentation and release notes, and test a full sign-in and token refresh against each MCP version you run.

Resource indicators and metadata documents

Resource indicators let a client name the MCP server a token is intended for, and client ID metadata documents let a client identify itself through a URL it hosts. Confirm whether your chosen Keycloak release provides each feature, whether it is enabled by default or needs explicit configuration, and whether your MCP clients can send resource indicators and fetch metadata documents. If either is missing, plan the manual client registration and token audience handling your team would need to maintain.

Experimental features and production status

Some features that MCP authorization depends on may be marked experimental and must be enabled explicitly in server configuration. List every feature flag your design relies on, then check the Keycloak documentation for what each one requires and whether the project treats it as supported. Keycloak states that breaking changes in a minor release will be opt-in, so confirm whether that commitment also covers experimental features. Decide whether your production risk accepts them, and document how you would disable a feature if it changes.

MCP client authentication methods

IDE agents, custom agents and vendor tools each authenticate in their own way, and not all of them will follow the flow your design expects. Inventory every client and record the OAuth grant type, client authentication method, redirect handling and token storage it uses. Check each vendor's documentation for these details, then run a test sign-in from every client against a staging realm before you finalize the client configuration in Keycloak.

Red Hat build or community release

Keycloak is available as the community release from the open source project, licensed under Apache 2.0, and as Red Hat build of Keycloak, Red Hat's supported distribution that replaces Red Hat Single Sign-On. Red Hat's product page showed version 26.6 as its latest, so confirm the current version and whether it includes the MCP-related features your design needs. Compare support lifecycle, patch cadence and certification scope with your internal support model, and ask Red Hat which features it supports in its build.

Questions buyers ask about Keycloak for MCP

What drives the cost of a Keycloak MCP authorization server project?

The cost follows the written scope. The main drivers are the number of MCP servers and clients to register, custom scope and policy design, evaluation of experimental features in your target release, high availability and operations setup, and testing across the MCP clients your users run. One-time work covers design, build, integration and testing. Recurring work covers upgrades, feature tracking, monitoring and token policy changes, which your team or a retainer may carry. Ask any quote to itemize each driver separately, state which MCP client versions are covered, and name who owns each follow-up task. DeployOpen does not publish prices, and a quote follows a written scope.

How long does a Keycloak MCP implementation take?

Duration depends on the written scope, not on a fixed number. It rises with the count of MCP servers and clients, the number of custom scopes and policies, how many experimental features need evaluation before a decision, and whether high availability is in scope. It also depends on how quickly your team provides the inventory, identity model and test clients. Ask for a timeline tied to named milestones, with the input each milestone needs from you. Keep testing across MCP clients as its own phase, because client behavior is often the slowest item to confirm. Most engagements are fixed-scope, so the agreed scope and timeline are written before work starts.

What must our team provide before an outside partner starts work?

Start with five inputs. Provide an MCP server inventory that lists each server, its owner and what it exposes. Provide the identity model, covering users, groups and any existing identity providers. Describe the target environment, including cloud accounts, clusters, network paths and the database platform. Supply test MCP clients that match what your users run. Name the people who make security decisions and who approves changes to scopes, tokens and client registration. Missing inputs usually move the schedule more than technical complexity does. Ask the partner to list these inputs in the scope document so gaps surface before kickoff.

Can our internal team set up Keycloak for MCP without a partner?

Yes, if the team has working Keycloak and OAuth 2.0 skills and the time to track experimental features. Confirm four things before you decide. Someone must design client registration and token audience rules. Someone must own high availability and upgrades. Someone must read the release notes for each Keycloak minor release. Someone must run tests across every MCP client your users rely on. A partner makes sense when those skills or hours are missing, or when a deadline is fixed. Many teams split the work, keeping operations in-house and bringing in outside help for design and testing.

Which Keycloak features for MCP are experimental, and what does that mean for us?

Treat each experimental feature as a documented decision with a named owner. Confirm which MCP-related features your target Keycloak release exposes behind a feature flag or labels as experimental, and read what the project says about their stability before you enable them. Record which features you accept, the exact release you pin, and who reviews each minor release for changes. Keycloak states that breaking changes in minor releases are opt-in, but confirm how that statement applies to any experimental feature. Run a test pass for each MCP client after every upgrade. List every enabled feature in the scope document, since that list drives both evaluation effort and ongoing tracking.

Does DeployOpen publish prices for Keycloak MCP work?

No. DeployOpen does not publish a price list. A quote follows a written scope that lists the MCP servers and clients, custom scope and policy design, experimental feature evaluation, high availability and operations setup, and testing across MCP clients. Ask for a quote that separates one-time build work from recurring items. Ongoing support, upgrades and continuous testing are available as retainers, so the quote should show what a retainer covers and what remains outside it. Engagements are generally fixed-scope, and the scope, deliverables and timeline are agreed in writing before work starts.

What goes wrong most often in Keycloak MCP deployments?

Most failures come from unclear ownership and untested assumptions rather than from the software itself. Watch for resource and audience settings that do not match what each MCP server validates. Watch for client registrations created by hand and never added to the inventory. Watch for experimental features enabled in one environment but not promoted to the others. Watch for upgrades applied without re-testing each MCP client. Check that the database and high availability design match the chosen Keycloak architecture, since the supported multi-site designs both require a synchronously replicated database. Confirm each item in the test plan before go-live, and keep a record of who signed off.

How DeployOpen scopes and supports a Keycloak MCP authorization server

DeployOpen treats Keycloak as an MCP authorization server as a fixed-scope implementation inside your own infrastructure. The written scope fixes which MCP servers, clients, resource indicators and token rules are in play before any build starts. Ongoing support, upgrades and continuous security testing are available as retainers after handover.

How we scope

The written scope lists each MCP server, client application and agent that will request tokens from Keycloak.
We confirm the MCP specification version and any experimental Keycloak features your servers depend on before design starts.
Engagements are fixed-scope, so deliverables, timelines and acceptance criteria are agreed in writing before work begins.

How we build

We build realm, client and scope configuration so each change can be reviewed and repeated.
Token audiences, resource indicators and client registration are tested against each MCP server's documented requirements.
Hardening follows Keycloak's production guidance: TLS everywhere, a path-restricted reverse proxy and a separate admin hostname.

How we hand over

Handover includes the configuration documentation, runbooks for realm and client changes, and the agreed test evidence.
Prometheus metrics are enabled on the management interface so your team can watch request and cache behavior.
Your team owns the environment afterward, and the handover names who approves Keycloak upgrades and operator updates.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover, scoped in writing.
Upgrades follow Keycloak's release notes, including opt-in breaking changes and the 26.8 upgrade notes on backchannel logout.
Security testing of the MCP server and agent flows can be added as a separate scoped engagement or retainer.

Keycloak as an MCP authorization server