OpenAPI → MCP Readiness
Score operations for tool conversion and generate a reviewable MCP tool-definition draft.
Run the audit to inspect operations.
What the readiness score measures
The audit rewards stable operation identifiers, precise summaries, detailed descriptions, documented parameters and successful response descriptions. It applies review penalties to state-changing methods, missing authentication context, very large input surfaces and ambiguous operation metadata.
Why conversion is more than schema translation
OpenAPI describes an HTTP interface. MCP exposes tools selected and populated by a model. A faithful conversion therefore needs good semantics, not just syntactically valid JSON Schema. Use the generated draft as a review artifact rather than as production server code.
A staged readiness review
First choose operations with one coherent purpose and stable identifiers. Split broad endpoints when a caller would struggle to predict which fields, modes or side effects apply. Next rewrite summaries and descriptions for tool selection: state when the capability is useful, distinguish it from nearby operations and explain the result without promising behavior the API cannot guarantee.
Review inputs after the semantics are clear. Parameters need accurate types, descriptions, requiredness and bounded values. Authentication material should normally remain in server configuration rather than model-supplied arguments. For state-changing operations, define approval, idempotency, retry and duplicate-request behavior. A well-shaped JSON Schema does not make a destructive call safe.
Finally test structured success and failure results. Map HTTP errors into actionable tool errors without leaking credentials or internal responses, apply timeouts, and verify that authorization is enforced by the underlying service. The generated definition is a starting artifact for this review; it does not implement an MCP transport, permissions or server lifecycle.
See the REST web services reference for resource and HTTP design, or study the contract layers before conversion.
Frequently asked questions
01Can every OpenAPI operation become an MCP tool?
Not automatically. Operations need clear intent, bounded inputs, useful descriptions and predictable structured results. Authentication, side effects and long-running workflows also need explicit handling.
02Why is operationId important?
A stable operationId provides a practical source for the tool name. Path and HTTP method alone often produce names that are difficult for people and models to distinguish.
03What makes an MCP tool description effective?
It should state the action, the situations in which the tool is useful, important limits and the meaning of the result. It should distinguish the tool from similar operations without marketing language.
04Why are destructive operations flagged?
POST, PUT, PATCH and DELETE operations may change external state. Tool integrations should represent that risk accurately and preserve a human approval path where appropriate.
05Does MCP use JSON Schema?
MCP tool definitions use JSON Schema for input parameters and can describe structured output with an output schema. The applicable protocol version determines specific requirements.
06Does the analyzer generate a complete MCP server?
No. It produces a readiness audit and a draft tool definition for suitable operations. Authentication, transport, error mapping and implementation code still require engineering work.
07Why does this tool accept JSON but not YAML?
The current browser release uses the built-in JSON parser to keep behavior small and inspectable. YAML parsing will require a separately versioned parser and security review.
08Should one large API become one MCP tool?
Usually not. An MCP server can expose focused tools. Each tool should have a coherent action and an input surface small enough for reliable selection and argument generation.
Interpret the score as triage, not certification
A high score means the document exposes several metadata signals that make an operation easier to review as a tool. It does not prove the description is true, the authorization model is correct or the operation is safe. A low score points to missing or ambiguous contract information; it does not mean the underlying API is unusable. Review the individual findings and the operation’s real behavior rather than setting an automatic deployment threshold.
Compare similar operations together. If two endpoints can retrieve overlapping resources, their tool descriptions must make the selection boundary obvious. If one operation starts a job and another reads its state, expose the lifecycle instead of implying a synchronous result. Parameters with opaque identifiers, free-form filters or unbounded text deserve examples and validation because they are common sources of incorrect calls.
Evidence for a production MCP implementation
Retain a versioned OpenAPI source, the reviewed tool definition and tests for valid input, invalid input, authorization failure, timeout, upstream failure and successful structured output. Add an explicit test for each side effect and retry rule. Logging should identify the operation and outcome without storing secrets or sensitive arguments by default.
Run selection tests with neighboring tools and realistic prompts, then inspect whether the tool name and description lead to the intended choice. This evaluation complements protocol and schema validation; it does not replace server-side permissions or human approval. Re-run the review when the API operation, security scheme, response model or MCP protocol version changes.