An MCP server demonstrating OAuth 2.0 authentication and scope-based authorization with JWT verification using Keycloak
This MCP server implements two simple utility tools (echo, to_upper) with adequate but minimal documentation. Both tools have clear names following verb_noun convention and explicit descriptions. However, parameter documentation is sparse, output schemas are not documented, and error handling is minimal. The server correctly registers tools with the Go SDK using mcp.AddTool(), and input schemas are visible in the struct tags. Descriptions meet the 20-char minimum but lack depth about when/why to use each tool. No parameter constraints (enums, patterns) are enforced. Error responses are generic. The code shows proper JWT-based authentication and scope-based access control in middleware, which is a security plus, but this is separate from tool quality. Overall, this is a straightforward educational example rather than a production-grade tool definition.
echo input back
returns the input string in uppercase
Parameter descriptions are minimal and lack guidance on constraints, format, or LLM-relevant context. The 'input' parameter in both tools has only 'the input to be echoed', no length limits, accepted character sets, or use-case guidance.
Output schemas are not documented. The tool descriptions do not state what fields are returned, what data types they contain, or how downstream tools should interpret the result. LLMs cannot plan tool chains without knowing response structure.
Tool descriptions lack context about when to use the tool versus alternatives, prerequisites, or side effects. 'echo input back' and 'returns the input string in uppercase' are functional summaries but do not guide LLM selection or reasoning.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 60 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 53 | - | v1 |
No error handling guidance. If a tool fails, there are no recovery hints, categorization of error types (retryable vs. user-fixable), or suggestions for next steps. The LLM receives a raw error with no actionable path forward.
No input validation or constraints declared in parameter descriptions. The 'input' parameter accepts any string with no length limit, character restrictions, or examples. This invites invalid LLM inputs and lacks self-documentation.