How to add Keycloak MCP Server to Windsurf

Manage Keycloak identity and access — users, realms, clients, roles, groups, IDPs and auth — over MCP. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 43★ · sse · oauth

Windsurf config for Keycloak MCP Server

docker pull quay.io/sshaaf/keycloak-mcp-server:latest

{
  "mcpServers": {
    "keycloak-mcp-server": {
      "serverUrl": "https://mcp-server.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}

Remote server — no local install needed. Restart the client after saving the config.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Keycloak MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Keycloak MCP Server's tools become available to Cascade.

Before you start

A running Keycloak instance (KC_URL) and realm (KC_REALM)
An OIDC client configured in Keycloak (OIDC_CLIENT_ID)
A user JWT token (obtainable via scripts/get-mcp-token.sh)
Docker (to run the container image) or a JVM/GraalVM build environment

What Keycloak MCP Server can do in Windsurf

User management

Create, read, update, delete and query Keycloak users.

Realm configuration

Manage and configure Keycloak realms.

Client administration

Administer Keycloak clients.

Role management

Manage realm and client roles.

Group management

Manage Keycloak groups.

Identity provider configuration

Configure identity providers (IDPs).

Authentication flow management

Manage Keycloak authentication flows.

Keycloak Discourse search

Search the Keycloak Discourse community for answers.

Security

Each user authenticates with their own JWT token issued by Keycloak; the token is passed as a Bearer credential in the Authorization header. Use the provided scripts/get-mcp-token.sh helper to obtain a token. Serve the SSE endpoint over HTTPS so bearer tokens are not exposed in transit.

Keycloak MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Keycloak MCP Server config there under the "mcpServers" key and restart the client.

Is Keycloak MCP Server safe to use with Windsurf?

How does authentication work?

Each user authenticates with their own JWT token issued by Keycloak. The token is passed as a Bearer credential in the Authorization header of the MCP client config. Use scripts/get-mcp-token.sh to obtain a token.

What transport does it use?

SSE transport over HTTP; the MCP client connects to the server's /mcp/sse endpoint.

How do I run it?

Pull and run the container image from quay.io/sshaaf/keycloak-mcp-server:latest, or build a JAR / GraalVM native image from source with Maven.

View repo Full Keycloak MCP Server page