An OpenAPI description can provide the raw material for MCP tools: operation names, documented inputs, response structures, and authentication requirements. A converter can use that material to generate a starting interface. Your team still needs to decide what the tools mean for a customer, how the adapter calls the real service, and whether the results remain correct under normal and unsuccessful requests.
Our recommendation is to treat generated tools as an integration draft. Review one complete mapping before expanding it across your API. If you have not yet chosen the initial scope, start with our guide to choosing which API actions to expose as MCP tools.
What can a converter reuse from OpenAPI?
OpenAPI describes HTTP operations, parameters, request bodies, responses, and security schemes. Parameters can live in different locations, including the path and query string, and their serialization has its own rules. These details are defined in the OpenAPI specification.
For a converter that supports the features used in your document, those declarations can drive much of the mechanical work:
- Propose a tool name from an operation identifier.
- Build candidate inputs from parameter and request-body schemas.
- Retain descriptions, permitted values, and required fields.
- Construct an HTTP request using a known operation and server.
- Use documented responses as a starting point for result handling.
Support varies between converters. Ask which OpenAPI versions and features a particular implementation handles, and inspect its output. A file that imports successfully is not evidence that every operation behaves correctly.
A worked example: searching a product catalogue
Consider an illustrative catalogue API with a product-search operation at GET /products. It accepts a search phrase, a list of categories, a maximum result count, and an optional cursor. This is a design example, not a tested customer integration.
Suppose a customer asks: “Find up to five desk lamps in the lighting category.” A useful tool might be named search_products, with inputs for the phrase, categories, limit, and cursor. Its description should explain that it searches the catalogue and does not place an order.
The adapter could translate those inputs into a request such as /products?q=desk%20lamp&category=lighting&limit=5. It would supply the appropriate credentials internally, call the configured service, and turn the response into a result the assistant can use.
The important review work is in the details of that translation. In this example, ask these questions before accepting the generated tool:
- What does the search phrase match? A title-only search and a search across descriptions can return different products. Document the actual behaviour.
- How are multiple categories encoded? Test two values, not just one. A single-category example can hide a serialization mistake.
- What does the limit mean? Decide whether it caps one page or the entire search, and make that boundary visible.
- How is the next page requested? Preserve the cursor as an opaque value. Do not have the assistant invent or reinterpret it.
- What does an empty result mean? Return an explicit empty result for a completed search, distinct from a service failure.
None of these questions is answered by counting how many tool definitions the converter produced.
Check schema references after conversion
A source document may reuse definitions through references. Copying an input schema into a different document can change the context in which those references resolve.
In JSON Schema, a $ref value is a URI reference resolved against a base URI. A relative reference without a usable base can fail to resolve. The JSON Schema guide to structuring schemas explains the underlying rules.
For our catalogue example, imagine that a category filter references a shared definition elsewhere in the API description. Inspect the generated tool to ensure that definition is still reachable and that its constraints are preserved. Validate the resulting schema as a standalone tool definition, rather than assuming that validation of the original API file proves the generated result is valid.
Our suggested review includes one valid input, one missing required input, and one value outside a documented constraint. Keep those examples beside the mapping so that a later regeneration can be checked against the same expectations.
Design the result the assistant actually needs
A catalogue response might include internal fields that have no role in a customer's search. We recommend returning a deliberate result shape: product identifiers, names, relevant URLs, the next-page cursor when applicable, and the information needed to answer the specific request. Include prices or availability only when your service supplies them with enough context to interpret them correctly.
For example, do not reduce a price to an unexplained number. If your API returns an amount and currency, preserve their relationship. If availability can change, describe the result as a lookup rather than implying that stock has been reserved.
MCP tools have an input schema and can declare an output schema. When an output schema is provided, structured results must conform to it; the protocol also describes returning a text representation for compatibility. See the MCP tool result requirements.
Choose that result contract deliberately. It should remain useful even if your internal HTTP response gains additional fields later.
Keep credentials and account selection out of guesswork
An authentication declaration in an API description is useful integration information. It does not decide how your product connects an assistant user to the correct customer account.
For the catalogue example, public search and customer-specific contract pricing would require different access decisions. Write those decisions down. Our recommendation is to derive sensitive account context from the authorized connection and enforce access in the service. Do not let a generated free-form account field become the only protection around another customer's data.
Similarly, the wrapper should call a configured upstream service. It should not expose a general-purpose destination URL merely because that is convenient for the adapter implementation. Review which inputs the assistant truly needs and which settings belong to the server operator.
How to accept a generated MCP integration
Use a small set of paired examples. For each one, capture the tool inputs, the intended HTTP request, and the expected customer-visible result. Our starting set for this catalogue would be:
- A normal search with one category.
- A search with two categories and special characters in the phrase.
- A request using the next-page cursor from a previous response.
- A completed search with no matches.
- A response where an expected field is missing.
- An expired or unauthorized customer connection.
First test the adapter against a controlled service or fixture. Then test realistic requests through the assistant client you intend to support. These checks answer different questions: whether the mapping works, and whether the assistant uses it appropriately.
Keep the generated definition, any intentional overrides, and the paired examples together in version control. When your OpenAPI file changes, review the tool changes before publishing them. A renamed input or altered result shape should be a conscious release decision.
Where to start with your own API
Pick one operation, generate its candidate tool, and walk through the request and response mapping with the person who maintains that API. Resolve ambiguous descriptions and unsupported schema features before generating the rest.
OpenAPI can make that work more repeatable, while MCP provides the interface through which assistants use the service. The useful deliverable is a dependable customer workflow supported by a reviewed mapping.
If you want a starting assessment of your documentation, the free Agent Readiness Audit proposes tools, provides a readiness score, and gives a fixed setup price. Use the proposed scope as the beginning of your integration review.