Provides tools for inspecting and modifying Keycloak realm, client, and protocol-mapper configuration across multiple Keycloak hosts, including listing clients, reading client config, managing protocol mappers, and handling client secrets.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@keycloak-mcp list realms on staging host"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server, stdio transport, that lets an AI assistant inspect and — behind explicit guards — modify Keycloak realm, client, and protocol-mapper configuration across multiple Keycloak hosts from a single server process.
Built on the official
@keycloak/keycloak-admin-client
and the @modelcontextprotocol/sdk.
Design derived from the MIT-licensed
Octodet keycloak-mcp — see NOTICE.
git clone https://github.com/Faust-Systems/keycloak-mcp.git
cd keycloak-mcp
npm install
npm run build # tsc → dist/Then create a config file (see Configuration) and register the server with your MCP client (see Registering with Claude).
Related MCP server: k8s-mcp-server
Every tool takes a host argument: a string key naming an entry in the
config file's hosts map (or discovered from the KC_<HOST>_* env
fallback — see below). Host keys are entirely arbitrary and user-defined
— there is no fixed list of hosts baked into this server. Point it at
whatever Keycloak instances you like, under whatever names make sense to you
(prod-eu, staging, customer-a, ...).
Each host entry carries its own explicit production flag:
"prod-eu": { "url": "...", "adminUser": "", "adminPassword": "", "production": true }production: true marks the host as production: writes against it are
refused unless allowProdWrite is also true in the config.
production: false marks it non-production: writes need only the
per-call write=true.
Fail-closed rule: if a host's production flag is absent, null,
or any non-boolean value, the host is treated as production. Only a
literal boolean false disarms the production write guard. This tool
rotates live client secrets, so a typo or an omission in config must never
silently disable the safety gate — when in doubt, it defaults to the safer
(more restrictive) behaviour.
The server authenticates per host with a password grant against the
admin-cli client on the master realm, and caches the admin client
per host (re-authenticating when the token expires). The target realm is a
per-call argument on every tool.
Read-only by default. Mutating tools (ensure_hardcoded_claim_mapper,
delete_protocol_mapper) take a write boolean that defaults to false.
Without write=true they return a dry-run plan and call no mutating API.
Production gate, fail-closed. Even with write=true, a write against a
production host is refused unless allowProdWrite is true in the config
file (or, when using the env fallback, KC_ALLOW_PROD_WRITE=true). A host
is production whenever its production flag is true, absent, or any
non-boolean value — only an explicit production: false opts a host out of
the gate. See Hosts.
No secrets, ever. Admin passwords and tokens are never logged or
returned; client secrets and registration access tokens are redacted from
get_client output.
Audit trail. Every successful write emits a structured JSON line to stderr: timestamp, host, realm, clientId, action, mapper name.
Idempotent verbs. ensure_hardcoded_claim_mapper reconciles toward a
desired state (already-present / update-with-diff / create) instead of
blindly creating; genuine ambiguity (e.g. two mappers already emitting the
claim) is reported as a conflict and never auto-resolved.
dump_client_secret and regenerate_client_secret handle real client secret
values. To keep those values out of the AI model's context entirely, the
server never returns or logs the value:
The secret value is written directly to a local file by the server
process (outPath, mode 0600, exact bytes, no trailing newline).
The tool returns only metadata — { host, realm, clientId, outPath, byteLength } (plus rotated: true for a regeneration). The value is never
in the return object, any log line, the audit line, or any error message.
Keycloak admin-API failures are reduced to an HTTP status plus a generic message, so no response body can leak.
The server warns (does not fail) if outPath's directory is
group/world-writable, since a secret file there could be exposed.
dump_client_secret is a read (no Keycloak mutation) so it is not
write-gated — but it still writes a local file. regenerate_client_secret
is a mutation: write=false (default) is a dry run, and rotating a
production host requires allowProdWrite (see the fail-closed rule under
Hosts).
All configuration — host URLs, admin credentials, and the production-write gate — comes from a single JSON config file. Nothing is hardcoded.
The config path is resolved in this order:
The environment variable KEYCLOAK_MCP_CONFIG, if set (explicit override).
Otherwise the default ~/.config/keycloak-mcp/config.json.
The file takes precedence. If no file is found at the resolved path, the server falls back to the legacy per-host environment variables (below) so nothing breaks — but when the file is present it is used exclusively and the env vars are ignored.
See config.example.json. Copy it to ~/.config/keycloak-mcp/config.json
and fill in your own host keys and credentials:
{
"hosts": {
"prod-eu": { "url": "https://keycloak.example.com", "adminUser": "", "adminPassword": "", "production": true },
"staging": { "url": "https://kc-staging.example.com", "adminUser": "", "adminPassword": "", "production": false }
},
"allowProdWrite": false
}Host keys ("prod-eu", "staging" above) are entirely arbitrary —
name your hosts however makes sense to you. There is no fixed set of
hosts; add or remove entries freely.
production (per host) gates writes behind allowProdWrite. Fail-closed
rule: if production is absent, null, or any non-boolean value, the
host is treated as production. Only a literal production: false opts a
host out. See Hosts.
allowProdWrite must be true to permit writes to any host whose
production flag resolves to production (per the rule above); a host
explicitly marked production: false only needs the per-call write=true.
A host with a missing url, adminUser, or adminPassword fails only when
addressed, with an error naming the missing field names (never values).
The other hosts keep working.
Calling a tool with a host key that isn't in the config fails with an
error naming the requested host and listing the configured host keys
(never values).
Protect the file: it holds admin credentials in the clear. Keep it at
chmod 600 — the server prints a one-line warning to stderr (it does not
refuse) if the file is group- or world-readable.
Used only when no config file exists at the resolved path. See .env.example.
Host keys are discovered by scanning for a KC_<HOST>_URL variable —
there is no fixed list. The host key is the captured part of the variable
name, lowercased, with underscores left as-is: KC_PROD_EU_URL yields the
host key prod_eu. Hyphens in a host key are not expressible via env
vars — use the config file if you need one.
variable | purpose |
| override the config file path (else |
| the host's base URL — presence of this variable is what discovers the host |
| admin credentials for that host |
|
|
|
|
npm install
npm run build # tsc → dist/
npm test # vitest unit testsBecause all credentials live in the config file, the MCP registration needs
only command + args — no env block:
{
"mcpServers": {
"keycloak": {
"command": "node",
"args": ["/absolute/path/to/keycloak-mcp/dist/index.js"]
}
}
}The server reads ~/.config/keycloak-mcp/config.json by default. To point it
at a different file, add a single override:
"env": { "KEYCLOAK_MCP_CONFIG": "/absolute/path/to/config.json" }Keep allowProdWrite at false in the file to hold production read-only;
set it to true only when a session must change production.
tool | arguments | what it does |
| host, realm | clients of a realm: |
| host, realm, clientId | full client representation (secrets redacted) |
| host, realm, clientId | the client's dedicated-scope mappers: id, name, type, config |
| host, realm, clientId, claimName, claimValue, addToAccessToken=true, addToIdToken=false, claimJsonType="String", write=false | idempotently ensure an |
| host, realm, clientId, mapperId, write=false | delete one mapper by UUID |
| host, realm, clientId, outPath | write the client's current secret to a local 0600 file; returns metadata only |
| host, realm, clientId, outPath, write=false | rotate the client secret and write the new value to a local 0600 file; returns metadata only |
realm claimGoal: the my-app client in realm acme on the staging host (configured
with "production": false, see Hosts) must emit a hardcoded
realm claim with value acme in access tokens.
Dry run (default — nothing changes):
ensure_hardcoded_claim_mapper with
{ "host": "staging", "realm": "acme", "clientId": "my-app", "claimName": "realm", "claimValue": "acme" }
→ returns status: "dry-run", wouldDo: "create" with the exact mapper it
would create — or wouldDo: "update" with a per-key diff if a mapper
already exists with different config, or status: "already-present" if
everything already matches.
Apply: same call plus "write": true.
→ creates/updates the mapper and emits an audit line to stderr.
Repeat against a production host (e.g. prod-eu) once verified — those
calls additionally require "allowProdWrite": true in the config file.
src/index.ts — server bootstrap + tool registration (stdio).
src/config.ts — config file loader (file → env fallback), perms warning.
src/hosts.ts — host registry, config validation, production write gate.
src/kc.ts — cached, re-authenticating admin client per host.
src/mappers.ts — pure plan/diff logic for the ensure tool (unit-tested).
src/secrets.ts — client-secret file-sink tools (value never returned/logged).
src/redact.ts — secret redaction.
src/audit.ts — stderr audit lines.
test/ — vitest unit tests for all pure logic.
MIT — see LICENSE. Derived from the design of Octodet's keycloak-mcp; see
NOTICE for attribution.
Delete one of a client's protocol mappers by mapper UUID. With write=false (default) it reports which mapper would be deleted; write=true performs the deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. | |
| write | No | false (default) = dry run: report what would happen without changing anything. true = apply the change. Production hosts additionally require KC_ALLOW_PROD_WRITE=true in the server environment. | |
| clientId | Yes | The client's clientId (the human-readable OAuth client id, not the UUID). | |
| mapperId | Yes | UUID of the protocol mapper (see list_protocol_mappers). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool can perform a dry run (write=false) or actual deletion (write=true), and mentions production safeguards via the 'host' parameter. It does not discuss irreversibility or post-deletion effects, but given no annotations, it carries the burden well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that cover the action, scope, and key parameter behavior. No unnecessary words, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 params, no output schema), the description covers the operation and parameter behavior adequately. It lacks details about the return value, but for a deletion tool this is acceptable. The reference to list_protocol_mappers aids completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by explaining the dry-run concept for 'write' and where to obtain 'mapperId' (from list_protocol_mappers), which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete one of a client's protocol mappers by mapper UUID'. It includes the key dry-run vs actual deletion distinction via the 'write' parameter, and the tool's purpose is distinct from siblings like list_protocol_mappers, which are for listing mappers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the dry-run mode and the 'write' parameter, giving guidance on how to safely use the tool. It does not explicitly state when not to use it or mention alternatives, but the purpose is clear and the context (sibling tools) provides some implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a confidential client's current secret and write ONLY the value to a local file (mode 0600, no trailing newline). The secret value is never returned to the caller or logged — the tool returns only metadata (path, byte length). This is a read against Keycloak (no mutation), so it is not write-gated.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. | |
| outPath | Yes | Absolute local file path the secret VALUE is written to (mode 0600). The value is written to this file by the server and is never returned to the caller. | |
| clientId | Yes | The client's clientId (the human-readable OAuth client id, not the UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully covers behavioral traits: writes file with mode 0600, no trailing newline, secret never returned or logged, only metadata returned, read-only against Keycloak. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each informative and necessary. Front-loaded with action, no unnecessary words. Appropriate length for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 4 params, description explains purpose, behavioral details, return metadata, and security aspects. It is sufficient for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameters are well-documented in schema. Description adds overall context but does not significantly enhance individual parameter meanings beyond what schema provides. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (fetch and write), resource (confidential client secret), and scope (write value to file, no return). Distinguishes from siblings by specifying it writes to file and does not return the secret, unlike regenerate_client_secret or get_client.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use (need secret written to file) and explains that it is a read operation not write-gated. However, does not explicitly state alternatives or when not to use, but implication is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Idempotently ensure a client has an oidc-hardcoded-claim-mapper emitting the given claim. Matches existing mappers by claim name: reports 'already-present' when the config matches, a diff + update when it differs, and a create when absent. With write=false (default) it only returns the plan; write=true applies it.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. | |
| write | No | false (default) = dry run: report what would happen without changing anything. true = apply the change. Production hosts additionally require KC_ALLOW_PROD_WRITE=true in the server environment. | |
| clientId | Yes | The client's clientId (the human-readable OAuth client id, not the UUID). | |
| claimName | Yes | The claim key to emit in tokens, e.g. "realm". | |
| claimValue | Yes | The hardcoded value the claim should carry. | |
| addToIdToken | No | Whether the claim is added to ID tokens (default false). | |
| claimJsonType | No | Keycloak claim JSON type label (default "String"). | String |
| addToAccessToken | No | Whether the claim is added to access tokens (default true). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses idempotent behavior, dry-run capability, and how it handles existing mappers (match, diff, create). Missing permission or side-effect details, but no annotations exist to supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, highly concise, front-loaded with key behavior. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 params, no output schema, no annotations), the description covers idempotency, matching logic, and dry-run. However, it lacks mention of return format or error handling, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds overall context but does not provide additional meaning for individual parameters beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ensures a client has a specific oidc-hardcoded-claim-mapper, using the verb 'ensure' and specifying the resource. It distinguishes itself from siblings like delete_protocol_mapper or list_protocol_mappers by its idempotent create-or-update behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the purpose and dry-run vs apply behavior, but does not explicitly state when not to use or list alternative tools. However, the context from sibling tools provides implied differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full representation of one client by clientId. Secret-bearing fields (client secret, registration access token) are always redacted.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. | |
| clientId | Yes | The client's clientId (the human-readable OAuth client id, not the UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that secret-bearing fields are always redacted, which is important. However, it does not mention other behavioral traits such as authentication requirements, rate limits, or whether the operation has side effects. The description covers basic safety but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the purpose. It is concise, but could be slightly more structured (e.g., separating purpose from behavior). However, it contains no wasted words and is effectively front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation, the description covers what the tool returns (full representation) and a key behavioral nuance (redaction). There is no output schema, so the description must stand alone. It does not mention error handling or edge cases, but it is sufficient for a clear API call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with detailed explanations for each parameter (host, realm, clientId). The description adds no additional parameter-level info beyond stating secret redaction. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Fetch' and the resource 'full representation of one client by clientId'. It distinguishes from siblings like list_clients (which lists many) and dump_client_secret (which extracts a specific field).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you need a single client's full data) but does not explicitly name alternatives or when not to use. The context of sibling tools makes the choice clear, but formal guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the clients of a realm on a Keycloak host. Returns clientId, internal UUID (id), and name for each client.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses return fields (clientId, UUID, name), which is helpful. As a list operation, it is implicitly read-only. With no annotations, the description adds value beyond the operation name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no unnecessary words. It is front-loaded with the core action and result format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (no output schema, few parameters), the description is nearly complete. It could mention that it returns a list of all clients, but the context signals support interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific information beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists clients of a realm on a Keycloak host, specifying the resource and action. It distinguishes from siblings by focusing on listing vs. the other tools' operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Sibling tools are listed but not referenced. The description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a client's dedicated-scope protocol mappers: id, name, mapper type (protocolMapper), and config.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. | |
| clientId | Yes | The client's clientId (the human-readable OAuth client id, not the UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It lists returned fields but does not disclose behavioral traits such as side-effects, read-only nature, pagination, error conditions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the action and key output fields. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description helpfully lists the return fields. However, it lacks details on pagination, ordering, or filtering. Still, it is complete enough for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add significant meaning beyond the property descriptions. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List' and the resource 'a client's dedicated-scope protocol mappers', and enumerates the returned fields (id, name, mapper type, config). This provides a specific and unambiguous purpose that distinguishes it from sibling tools like delete_protocol_mapper or ensure_hardcoded_claim_mapper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, context, or cases where other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rotate a confidential client's secret and write ONLY the NEW value to a local file (mode 0600, no trailing newline). The secret value is never returned to the caller or logged — the tool returns only metadata. This mutates Keycloak: with write=false (default) it returns a dry-run plan and rotates nothing; with write=true it rotates. Production hosts (us/za) additionally require allowProdWrite in the config.
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | Target Keycloak host key, as configured in the config file's "hosts" map (or the KC_<HOST>_* env fallback). A host whose "production" flag is true, or absent, is treated as PRODUCTION and its writes are gated by "allowProdWrite". | |
| realm | Yes | Target realm name for the operation. | |
| write | No | false (default) = dry run: report what would happen without changing anything. true = apply the change. Production hosts additionally require KC_ALLOW_PROD_WRITE=true in the server environment. | |
| outPath | Yes | Absolute local file path the secret VALUE is written to (mode 0600). The value is written to this file by the server and is never returned to the caller. | |
| clientId | Yes | The client's clientId (the human-readable OAuth client id, not the UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Fully discloses that the secret is never returned or logged, only metadata is returned; mutates Keycloak; is a write operation; production gating; file mode 0600 and no trailing newline; all behavioral traits are explained beyond what annotations would provide (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact single paragraph with no wasted words. All critical information is front-loaded and each sentence contributes unique value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers return value (metadata), side effects, production guard, dry-run capability, file writing details, and parameter semantics. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, but description adds significant value: explains host's production flag, dry-run vs. apply for write, file path specifics (mode 0600, server-side write), and clientId as human-readable OAuth id. Each parameter gets richer context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool rotates a confidential client's secret and writes the new value to a local file. Distinguishes itself from siblings by explicitly noting 'ONLY the NEW value' and write-to-file behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the write parameter for dry-run vs. actual rotation and mentions production hosts require allowProdWrite. Does not compare to dump_client_secret or other siblings, but provides clear context for when to use each mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0delete_protocol_mapperdump_client_secretensure_hardcoded_claim_mapperget_clientlist_clientslist_protocol_mappersregenerate_client_secretEach tool has a clearly distinct purpose: listing clients, getting one client, dumping/regenerating secrets, and managing protocol mappers (list, delete, ensure a specific type). No overlap or ambiguity.
All tools follow a consistent verb_noun pattern in snake_case (e.g., list_clients, get_client, dump_client_secret). No mixing of conventions or unclear naming.
7 tools is well-scoped for the focused domain of Keycloak client secrets and protocol mapper management. Not excessive, and each tool serves a clear purpose.
The tool set covers core operations for client secrets and protocol mappers, including reading, idempotent ensures, and deletions. Minor gaps exist (e.g., no generic protocol mapper creation or client CRUD), but the surface is coherent for its intended scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Faust-Systems/keycloak-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
