Skip to main content
Glama

skycloak_query_events

Read-only

Query Keycloak user and admin events for a cluster to inspect logins, token grants, and admin operations, with filters for realm, time, event type, and offset paging.

Instructions

Query Keycloak user and admin events for a cluster (logins, token grants, admin operations). Filter user events with types/error, admin events with operation_types, and either with realm, start_time/end_time, and offset. Note search only matches username, client_id, realm_name and ip_address; it does not match the event type, so use types or operation_types for that. Limit is capped at 100 per call, so page with offset for anything larger.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cluster_id": "<cluster_id>"
    },
    "name": "skycloak_query_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
errorNofilter user events by Keycloak error code, e.g. invalid_user_credentials
limitNomax events to return (default 50, max 100)
orderNotimestamp sort order: asc or desc (case-insensitive, default desc)
realmNofilter by realm name
typesNouser event types to match, e.g. LOGIN, LOGIN_ERROR, LOGOUT, REGISTER (case-insensitive). User events only
offsetNonumber of events to skip, for paging past the 100-per-call cap
searchNosubstring match over username, client_id, realm_name and ip_address only; does NOT match event type
categoryNoevent category: user or admin (case-insensitive)
end_timeNoinclusive end time, RFC3339
usernameNofilter by username
cluster_idYesthe cluster ID
start_timeNoinclusive start time, RFC3339. Without it the API only covers the last 24 hours
operation_typesNoadmin operation types to match: CREATE, UPDATE, DELETE or ACTION (case-insensitive). Admin events only

Output Schema

NameRequiredDescriptionDefault
countYes
eventsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior not in the annotations: a hard 100-events-per-call cap, the need to page with offset, and the implicit 24-hour default window when start_time is omitted. It does not discuss auth/permission requirements, but the added operational constraints are substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, each carrying a distinct load: scope, filter semantics, and paging constraint. The most important caveat (search does not match event type) is placed inline with the filter guidance rather than buried, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 13 parameters and an output schema present, the description covers the highest-risk semantics: the 100-item cap, offset paging, the default 24-hour window, and the search limitation. A minor gap remains around what happens when category is omitted (user and admin events both returned?), but overall it is sufficient to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description goes further by clarifying parameter interactions rather than restating fields: search is a substring match limited to username/client_id/realm_name/ip_address and explicitly will not match event type, and types vs operation_types are scoped to different event categories. That cross-parameter meaning is exactly what an agent needs to avoid a silent empty result.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Query Keycloak user and admin events for a cluster') and enumerates the event kinds covered (logins, token grants, admin operations), which is enough for an agent to distinguish this from export-style siblings such as skycloak_export_cluster_events.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete guidance on which filters apply to which event stream (types/error for user events, operation_types for admin events) and prescribes the paging workflow via offset. It stops short of naming a specific alternative tool or exclusion condition, so it is strong context rather than full when/when-not routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools