An MCP server that converts OpenAPI/Swagger specifications into MCP tools, enabling LLMs to call API operations defined in OpenAPI specs
OpenAPI-MCP exposes 4 tools with critical quality gaps. Tool definitions lack proper descriptions, parameter documentation, and schema clarity. The 'initialize' tool violates MCP stateless protocol design by treating this as a handshake. 'tools/call' accepts arbitrary 'arguments' without type validation. Error handling is minimal. Output schemas are not documented. No tool annotations (readOnlyHint/destructiveHint/idempotentHint). The server attempts to expose an OpenAPI spec as MCP tools, but the wrapping layer itself has poor definitions.
Initialize the MCP connection and receive protocol version and capabilities
Set the logging level for the MCP server
Execute an API operation by name with provided arguments, making HTTP requests to the target API
List all available tools from the parsed OpenAPI specification
Tool 'initialize' violates MCP stateless protocol. MCP 2026-07-28 spec requires each request to be self-contained with _meta containing protocol version and capabilities. This tool replicates pre-2025 stateful handshake pattern (Mcp-Session-Id model, removed). 'connectionId' parameter is a session identifier, incompatible with current spec.
Tool 'tools/call' has 'arguments' parameter defined as generic object with no type constraints, property definitions, or validation hints. LLMs cannot reason about what 'arguments' accepts. No minProperties, maxProperties, additionalProperties, or required subfields documented. This invites arbitrary, malformed input.
No output schema documented for any tool. 'tools/list' presumably returns available tools, but the response structure is undocumented. 'tools/call' returns a tool result, but format/fields are not specified. LLMs cannot plan downstream calls or extract required fields without knowing output shapes.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 36 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Descriptions are missing or trivially short. 'tools/list': 28 chars (below 34-char baseline p10). 'tools/call': 93 chars but vague ('Execute an API operation by name', does not explain when to use vs other tools or prerequisites). 'logging/setLevel': 43 chars, unclear impact. Descriptions do not follow 'WHAT, WHEN, prerequisites' format. No examples of logging level values ('info', 'debug', 'error') explicitly listed as enum.
Parameter 'level' in logging/setLevel has no enum constraint. Description says 'e.g., info, debug, error' but does not declare these as valid values. LLMs may pass arbitrary strings ('verbose', 'trace', 'silent'). Enums must be machine-parseable in schema, not example text.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). 'tools/call' is destructive (WRITE risk flagged), but schema lacks destructiveHint. 'tools/list' and 'initialize' are read-only but lack readOnlyHint. Without annotations, agents cannot reason about retry safety or side effects.
Error handling is minimal. No recovery guidance. If tools/call fails (e.g., invalid operation name, API timeout, authentication error), no error structure hints next steps. Code shows generic error responses (jsonError with code/message/data) but no actionable recovery messages.
Logging tool ('logging/setLevel') leaks into tool surface. Logging is a server control feature, not an agent-invokable tool. Per MCP 2026-07-28, logging is configured per-request via _meta.io.modelcontextprotocol/logLevel in request headers. Exposing logging/setLevel violates the deprecated Logging pattern (removed from spec). Should be removed.
No parameter validation rules documented. 'name' in tools/call is unconstrained (any string). No guidance on case sensitivity, namespace prefixes, or character restrictions. 'connectionId' in initialize: what format? UUID? Opaque? No description.
Secret injection not addressed. If the underlying OpenAPI spec requires API keys or auth tokens, tool description does not clarify how agents obtain credentials. Does tools/call accept an optional 'Authorization' header? Must credentials be configured server-side? Unclear.