OpenAPI to MCP bridge - translates OpenAPI 3.0 operations into MCP tool definitions and exposes them over stdio, HTTP, or SSE transports
mcpgen is a code generator that translates OpenAPI specs into MCP tool definitions. The 5 tools shown have basic schemas and descriptions derived from OpenAPI, but fall short of production quality. Tool names lack clear action verbs (postUpdate, postBulkUpdates are HTTP-centric rather than intent-centric). Descriptions are minimal (10-50 chars) and do not explain WHEN to use each tool or what happens on success/failure. Parameter descriptions are sparse or missing entirely. No evidence of error handling guidance, output schema documentation, or idempotent/destructive operation markers. The adminSecret tool exposes a sensitive endpoint with no access control hints. Schemas are present but lack constraints (enums, ranges, patterns) and parameter descriptions are absent or trivial.
GET /admin/secret - Retrieve admin secret
DELETE /updates/{id} - Delete an update
GET /employees/{id}/timeline - Retrieve employee timeline
POST /updates/bulk - Create multiple updates
POST /updates - Create an update
Tool names are HTTP-method-centric (postUpdate, postBulkUpdates, deleteUpdate) rather than action-verb-centric. LLMs infer intent from names, 'postUpdate' does not clearly convey 'create an update' or 'submit a project update'. Rename to create_update, create_bulk_updates, delete_update.
Descriptions are too short (10-50 chars) and lack context. 'POST /updates - Create an update' is a bare API endpoint label, not an LLM-optimized description. Missing: WHEN to use this tool, what it returns, and whether it has side effects. Expand to 50-200 chars with intent and outcome.
Parameter descriptions are missing or trivial. 'remarks' has no description; 'date' says only 'Update date' without format guidance; 'projectId' lacks context on whether it is required or how to obtain it. Every parameter needs a description explaining what it controls and valid values/ranges.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 39 | 2026-07-28+ | v2 |
adminSecret tool exposes a sensitive endpoint with no access control hints or warning. Tool description does not indicate this is a privileged operation or that it requires special permissions. Security-sensitive tools must declare required scopes and warn of access restrictions.
No error handling guidance. Tools lack descriptions of failure modes, recovery steps, or actionable error messages. E.g., deleteUpdate does not explain what happens if the ID does not exist or if the user lacks permission. Error responses must guide the LLM on next steps.