Click on "Deploy 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., "@clue2app-user-mcp list all users"
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.
MCP server exposing coordinator's user/membership/role admin operations as
tools for LLM callers (agents, Claude Desktop, etc.). Every tool is a thin
passthrough to coordinator's /api/users/* endpoints — RBAC is enforced
entirely by coordinator using the caller's bearer token; this service does
not validate or interpret tokens itself.
Group | Tool | Coordinator endpoint |
users |
|
|
users |
|
|
users |
|
|
users |
|
|
users |
|
|
memberships |
|
|
roles |
|
|
roles |
|
|
Related MCP server: mcp-keycloak
cd clue2app-user-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
export COORDINATOR_URL=http://localhost:8081 # or your coordinator base URL
export COORDINATOR_TOKEN=<a coordinator-issued bearer token>
user-mcp # defaults to --transport=stdio
# or: python -m user_mcp.server --transport=stdioPoint an MCP-capable client (Claude Desktop, mcp dev, etc.) at the
user-mcp command with those two env vars set. stdio has no per-request
auth header, so the token is read once from COORDINATOR_TOKEN at startup
and reused for every tool call in that session.
python -c "
import sys; sys.path.insert(0, 'src')
from user_mcp import server
print([t for t in dir(server) if not t.startswith('_')][:5])
"The Knative/kpack deployment runs the SSE transport, which reads the bearer
token per-request from the inbound Authorization: Bearer <token> header —
each caller supplies their own token, so a single instance safely serves
many callers at different privilege levels.
python -m user_mcp.server --transport=sse --port=$PORTThis is exactly what Procfile runs. Paketo's Python buildpack detects
pyproject.toml directly (no requirements.txt needed, no Dockerfile
needed) and uses python -m so we don't depend on where the buildpack
places console-script shims in the launch image.
Env vars
Var | Required | Notes |
| yes | e.g. |
| stdio only | ignored by the SSE transport |
| no | Knative-injected; defaults to 8080 |
No secrets are baked into this service — every tool call carries its own token, and the service holds nothing longer than the lifetime of a single request.
GET /sse — MCP session endpoint (SSE transport)
POST /messages — MCP message endpoint (SSE transport)
GET /health — 200 {"status": "ok"}, no coordinator round-trip. Wire
both readinessProbe and livenessProbe to this path — a coordinator
outage must not cascade into MCP pod restarts.
src/user_mcp/
├── server.py # FastMCP init, CLI dispatch, /health, transport wiring
├── coord_client.py # httpx.AsyncClient wrapper, bearer passthrough
├── auth.py # bearer_from_context() using a contextvar
└── tools/
├── users.py # list/get/disable/enable/resolve_duplicates
├── memberships.py # list_user_memberships
└── roles.py # grant/revoke_roleDisable a user account. Requires SYSTEM token. Records the given reason for audit.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must cover behavioral traits. It discloses the need for a SYSTEM token and that the reason is recorded for audit, but it omits details such as reversibility, impact on user data, or concurrent effects.
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 concise sentences front-load the purpose and add key constraints. No unnecessary words.
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 and no annotations, the description partially covers the tool's behavior but lacks details on what disabling entails (e.g., can the account be re-enabled? Are there side effects on data?). More context would improve 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?
The schema has no description coverage for parameters (0%), and the description only indirectly references the 'reason' parameter by saying 'Records the given reason for audit'. The 'id' parameter is not mentioned. More explicit parameter context is needed.
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 'Disable a user account' with a specific verb and resource. It distinguishes from sibling tools like enable_user by indicating it requires SYSTEM token and records an audit reason.
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 the prerequisite ('Requires SYSTEM token') and mentions the audit side effect. However, it does not explicitly advise when to use alternatives (e.g., enable_user) or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-enable a previously disabled user account. Requires SYSTEM token.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions the token requirement but omits details about side effects, reversibility, or idempotency of the enable operation, which is important for a mutation tool.
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 exceptionally concise with two short sentences, front-loading the purpose without any wasted words.
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 tool's simplicity (one parameter, no output schema), the description is minimally adequate. However, it lacks behavioral context that would help an agent use it correctly, such as whether the operation is reversible or what state the user will be in after re-enablement.
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 0% because the tool description does not mention the 'id' parameter. The schema itself provides a description, but the tool description must compensate for low coverage and does not, adding no value beyond 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 states the specific verb 'Re-enable' and resource 'previously disabled user account', clearly distinguishing it from its sibling tool 'disable_user' and other user management tools.
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 includes a clear prerequisite ('Requires SYSTEM token') and implies the tool is used when a disabled user needs to be re-enabled. However, it does not explicitly state when not to use this tool or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single user record by id.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies read-only behavior but does not specify authentication requirements, error handling, or response structure. Acceptable for a simple fetch but minimal.
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?
Single sentence, no fluff. However, the brevity comes at the expense of completeness, such as missing response details.
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 read tool with no output schema, the description is minimal. It omits what happens on missing id, error scenarios, or fields returned. Adequate but not thorough.
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 0% description coverage (according to context), and the description adds no value beyond the schema: 'by id' repeats what the schema already implies. For a single parameter, baseline would be 3 if schema covered it, but here it does not.
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 fetches a single user record by id. The verb 'fetch' and resource 'user record' are specific, and the qualifier 'by id' distinguishes it from list or mutation tools like list_users or disable_user.
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 vs alternatives such as list_users or disable_user. The description lacks context for selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grant a user a role on a project. Requires SYSTEM or ACCOUNT_ADMIN token.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions authorization requirements but does not disclose behavioral traits such as idempotency, error handling, or whether granting a role twice is allowed. No annotations are provided.
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?
A single, concise sentence that efficiently communicates the tool's purpose and a key prerequisite. No unnecessary words.
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 tool with three parameters and no output schema, the description adequately covers purpose and authorization. It does not describe return values or error scenarios, but the tool's simplicity limits the gap.
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 already provides descriptions for each parameter. The tool description does not add further meaning beyond the schema. Baseline score of 3 is appropriate since the schema covers the parameters.
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 ('Grant a user a role on a project'), using a specific verb and resource. It distinguishes from sibling tools like revoke_role.
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 includes the required authorization token type, providing clear context for when the tool can be used. However, it does not compare with alternatives or specify when to use this over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every project a user belongs to, with their role on each.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
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 mentions a read operation but omits behavioral traits like pagination, ordering, or what happens if the user has no memberships. The description is minimal and does not add significant transparency beyond the purpose.
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 of 10 words, front-loading the verb and resource with no extraneous information. It is highly concise and well-structured.
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 and no output schema, the description is adequate for a simple read list tool: it specifies input (user) and output (projects and roles). However, it lacks details on error handling or edge cases, making it minimally complete.
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 0%, yet the description does not add meaning to the parameter 'id' beyond what the schema provides (simply 'User id'). The description could clarify the format or constraints but does not, leaving the agent with insufficient guidance.
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 uses a specific verb (List) and clearly states the resource (every project a user belongs to, with their role). This distinguishes it from siblings like list_users (lists user accounts) and get_user (single user details), providing strong purpose clarity.
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 usage when needing to find a user's project memberships, but does not explicitly state when to use this tool versus alternatives (e.g., grant_role for modifying roles). No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List users, optionally filtered by search query or project membership.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavior. It only mentions listing and filtering, omitting pagination (limit/offset), default returns, or any side effects. Does not confirm read-only nature.
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?
Single sentence of 12 words, efficient and front-loaded with the core action and optionality. No superfluous content.
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 or output schema, the description is too sparse. It lacks details on pagination behavior, result ordering, or return format, which are critical for a filtered-list tool with multiple parameters.
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 0% schema description coverage, the description adds 'optionally filtered by search query or project membership' for query and project_id, but ignores limit and offset. Incomplete compensation for missing schema details.
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 states 'List users' with optional filtering, clearly distinguishing from sibling tools like get_user (single user) and disable_user/enable_user (status changes).
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 usage for listing users with optional filters but does not specify when to prefer this over alternatives or provide exclusions. No guidance on when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge duplicate_ids into primary_id, keeping primary_id as the surviving user. Requires SYSTEM token.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavioral traits. It indicates a destructive write operation (merging and removing users) but lacks details on reversibility, side effects, or constraints beyond the token requirement.
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 with two sentences: the first states the core functionality, the second a critical requirement. No wasted words or redundancy.
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 lack of annotations and output schema, the description is somewhat minimal. It covers the basic operation and a requirement, but omits potential edge cases, return format, and error conditions that would be helpful for a destructive merge tool.
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 already provides clear descriptions for both parameters ('User id to keep' and 'User ids to merge into primary_id and remove'), so the description adds no additional semantic value beyond confirming the merge action.
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's action: 'Merge duplicate_ids into primary_id, keeping primary_id as the surviving user.' It uses a specific verb and resource, and is distinct from sibling tools which handle enable/disable, listing, and role management.
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 mentions the prerequisite 'Requires SYSTEM token' but does not explicitly state when to use this tool vs alternatives. The purpose is clear from context, but exclusion criteria or when-not-to-use guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke a user's role on a project. Requires SYSTEM or ACCOUNT_ADMIN token.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It indicates the action is a write operation and mentions token requirements, but lacks details on side effects, error conditions, or return behavior.
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 (one sentence) and front-loaded, containing only essential information without any extraneous 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?
For a simple revocation tool with three parameters and no output schema, the description covers the core action and token requirement, though it could include more behavioral details like idempotency or error handling.
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 description provides no parameter information, and the context signals indicate 0% schema description coverage. Although the schema itself has descriptions, the tool description does not add meaning beyond 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 action ('Revoke a user's role on a project') and the required resource, distinguishing it from sibling tools like grant_role.
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 specifies the required token type ('Requires SYSTEM or ACCOUNT_ADMIN token') as a prerequisite, but does not provide explicit guidance on when to use or not use this tool versus alternatives.
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.
v0.1.0disable_userenable_userget_usergrant_rolelist_user_membershipslist_usersresolve_duplicate_usersrevoke_roleScored across 8 tools
Each tool has a clearly distinct purpose: disabling, enabling, fetching, granting roles, listing memberships, listing users, resolving duplicates, and revoking roles. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., disable_user, grant_role). Naming is predictable and uniform.
8 tools is well-scoped for user management, covering core operations without unnecessary bloat.
The set covers enable/disable, role management, and listing, but lacks create_user and delete_user, which are minor gaps for a user management server.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Remote MCP for A2A caller identity, scope policy, verdict receipts, and audit history.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
