Keycloak Provider

Use the Keycloak provider when a Keycloak realm is your OAuth authorization server. MCP clients register directly with Keycloak, and your MCP server verifies Keycloak JWTs against the realm JWKS. This guide covers the Keycloak setup path. Use the auth providers API reference for exact oauthKeycloakProvider() options, defaults, and errors.

Prepare the Keycloak realm

You need Keycloak 26.4 or later, a reachable realm, and admin access. Keycloak 26.4 added the RFC 8414 authorization-server metadata that MCP clients need for this flow. For local setup, start with the Keycloak getting started guides. Enable Dynamic Client Registration for the hosts your MCP clients use:

Go to Realm settings > Client registration > Anonymous Access Policies.
Open Trusted Hosts.
Add local client hosts such as localhost and 127.0.0.1.
Keep Client URIs Must Match enabled.

Browser-based MCP clients also need the Allowed Registration Web Origins policy in Keycloak 26.6 and later. Add each browser client origin, such as http://localhost:6274 for local inspector workflows. For production, avoid anonymous DCR only after you have confirmed your MCP clients can send a Keycloak Initial Access Token during Dynamic Client Registration. The mcp-use server provider only configures token verification; the client performs registration directly with Keycloak.

Set environment variables

MCP_USE_OAUTH_KEYCLOAK_SERVER_URL=http://localhost:8080
MCP_USE_OAUTH_KEYCLOAK_REALM=demo

Set an audience only when your Keycloak realm includes the matching aud claim through an audience mapper.

MCP_USE_OAUTH_KEYCLOAK_AUDIENCE=https://mcp.example.com/mcp

If you set an audience but Keycloak does not emit that aud value, valid-looking tokens will be rejected.

Configure the MCP server

import { MCPServer } from "mcp-use";
import { oauthKeycloakProvider } from "mcp-use/oauth/keycloak";

const server = new MCPServer({
  name: "keycloak-server",
  version: "1.0.0",
  oauth: oauthKeycloakProvider(),
});

await server.listen(3000);

You can pass the server URL and realm directly instead of using environment variables:

oauth: oauthKeycloakProvider({
  serverUrl: "https://keycloak.example.com",
  realm: "demo",
});

Use Keycloak roles in tools

The provider maps Keycloak realm roles onto ctx.auth.user.roles. It maps resource roles onto ctx.auth.user.permissions as client:role strings.

import { error, text } from "mcp-use";

server.tool(
  {
    name: "admin_action",
    description: "Run an admin-only action.",
  },
  async (_args, ctx) => {
    if (!ctx.auth) {
      return error("Unauthorized");
    }

    if (!ctx.auth.user.roles?.includes("admin")) {
      return error("Forbidden: admin role required.");
    }

    return text("Done.");
  },
);

Use resource-role permissions when different Keycloak clients own different permissions.

Verify the setup

Run the server and connect with an OAuth-capable MCP client.

npm run dev

Confirm these cases:

The client discovers Keycloak OAuth metadata.
The client registers with Keycloak.
Authenticated tool calls include ctx.auth.user.userId.
Role-protected tools reject users without the required role.

Production checks

Before deploying:

Serve Keycloak and the MCP server over HTTPS.
Use Initial Access Tokens or stricter registration policies only with clients that can pass the registration token to Keycloak.
Add an audience mapper before setting MCP_USE_OAUTH_KEYCLOAK_AUDIENCE.
Decide whether tools should check realm roles, resource roles, or both.

Next steps

Runnable Keycloak example

Compare your setup with a working mcp-use Keycloak server.

Keycloak Client Registration

Review Keycloak Dynamic Client Registration.

User Context

Use Keycloak roles and permissions inside tools.