> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak Provider

> Configure Keycloak Dynamic Client Registration authentication for a TypeScript MCP server.

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](/typescript/api-reference/server/auth-providers#oauthkeycloakprovider) 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](https://www.keycloak.org/guides#getting-started).

Enable Dynamic Client Registration for the hosts your MCP clients use:

1. Go to **Realm settings > Client registration > Anonymous Access Policies**.
2. Open **Trusted Hosts**.
3. Add local client hosts such as `localhost` and `127.0.0.1`.
4. 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

```bash theme={null}
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.

```bash theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
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.

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Runnable Keycloak example" icon="github" href="https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/mcp-use/examples/server/oauth/keycloak">
    Compare your setup with a working mcp-use Keycloak server.
  </Card>

  <Card title="Keycloak Client Registration" icon="book-open" href="https://www.keycloak.org/securing-apps/client-registration">
    Review Keycloak Dynamic Client Registration.
  </Card>

  <Card title="User Context" icon="user" href="/typescript/server/authentication/user-context">
    Use Keycloak roles and permissions inside tools.
  </Card>

  <Card title="Keycloak provider API reference" icon="terminal" href="/typescript/api-reference/server/auth-providers#oauthkeycloakprovider">
    Look up exact provider options and defaults.
  </Card>
</CardGroup>