By: Nelson M. Nones CPIM, Founder, Chairman and President, Geoprise Technologies Corporation

My first boss, Ken Bordner, was fond of constantly telling me, “you may know theory but, goddammit, I know it practical!”

So it is with building Model Context Protocol (MCP) servers from OpenAPI documentation. In this post, I’ll explain:

• How hard it is to produce production-grade OpenAPI specifications;
• Once they are production-ready, how easy it is to generate MCP servers; and
• Gotchas you won’t have to worry about when deploying our newly-published GM-X Auto OpenAPI MCP Bridge documentation.

Preparing OpenAPI Documentation

The OpenAPI specification, established in 2016, is derived from Swagger, an application programming interface (API) project which first appeared in 2011―13 years before Anthropic introduced the MCP standard. Over the years it evolved to become the de facto standard for describing Representational State Transfer (REST) APIs because it facilitates the automated production of machine-readable contracts between providers and consumers of Web services. According to Riya Sethi, a Senior Software Engineer for Truto, a unified API and embedded integration platform, raw OpenAPI specifications are

written for humans who read documentation and machines that validate payloads.

One prominent feature of the OpenAPI specification is its support for modularization and re-use by references that point to objects or components defined elsewhere in the same file, in a separate file on the same local machine, or even on a remote machine. The specification strongly encourages references to eliminate redundancy, improve readability, and simplify maintenance―exactly the same benefits developers reap from normalizing databases or writing subroutines. Accordingly, all source code for Geoprise’s GM-X Auto OpenAPI documentation is generated and maintained in highly modular “referenced” form wherein each path has its own file, and re-usable schema components are documented in a separate file.

The creators of Swagger and OpenAPI never envisioned supporting MCP; instead, MCP relies upon OpenAPI-compliant documentation as a complete, machine-readable contract setting out API endpoints, parameters, and schemas that the protocol requires to make remote procedure calls (RPCs) on behalf of Large Language Model (LLM) applications such as Claude Desktop or the ChatGPT Desktop App. Sethi explains that LLMs neither read documentation nor validate payloads; they

read schemas as prompts. A description field is not metadata to them; it is the instruction.

Furthermore, according to Sethi, MCP requires schemas to be 

completely self-contained, meaning they cannot reference anything outside themselves. This requires ‘dereferencing’ – a process of resolving all references and inlining them into a single schema,

including detection of recursive references to avoid infinite loops.

For us, dereferencing meant having to undo all the hard work already invested in modularizing our GM-X API documentation by reference. We discovered through trial and error that to ward off server-side request forgery (SSRF) attacks and threats posed by path traversal vulnerabilities, the most forgiving of the MCP server generators we tested would only resolve references to components within the same document―even when an option to allow external references is available. To work around those safeguards, we had to copy and bundle together the schemas for each path by API, and also append a copy of the re-usable components to every bundle.

Even after bundling, however, we found that none of the MCP server generators were capable of successfully resolving internal references to path item or schema objects outside the components section of the API documentation, despite the fact that, for e.g. path item objects, Versions 3.x of the OpenAPI specification allow us to

logically replace the [referencing object] with a Path Item Object that combines the [referenced object’s] fields with [other] fields of the [referencing object], as long as none of those fields conflict.

We ultimately overcame that limitation by re-labeling all remaining path item and schema object references within API bundles using the description keyword. This tactic eliminates resolution errors when generating MCP servers, while preserving our API bundles’ human readability.

Such limitations, I believe, reflect the relative immaturity of MCP server generation software. Let’s not forget that, as I write this, the MCP protocol isn’t quite two years old, and getting AI agents up to speed using MCP has been a much higher industry priority than making MCP server generator software smarter.

Moreover, our workaround has no adverse impact whatsoever on out-of-the-box performance of automatically generated MCP servers, because only in output schema do we re-label references as descriptions in our API bundles. Unlike input schema, output schema are optional for MCP server tools, according to Sections 5.1 and 5.2.7 of the MCP Specification, and MCP server generator developers apparently assume that LLM applications require no further assistance when parsing whatever output they receive from tool responses. Should such assumptions prove wrong, then the human-readable descriptions inside our API bundles will make it much easier to add output schemas manually where needed to improve the performance of MCP server tools.

All of our 452 API bundles are available from GitHub as OpenAPI documents in JavaScript Object Notation (JSON) format. Each bundle is a single file artifact comprising a fully self-contained assembly of OpenAPI components to promote error-free use. This is the preferred way of interacting with Geoprise GM-X Auto OpenAPI descriptions when generating MCP servers automatically.

Generating MCP Servers Automatically

This process is highlighted in Figure 1, below.

Figure 1 –  Automatic MCP Server Generation Process

You can install and use the self-hosted open-source openapi-mcp-generator to generate MCP servers automatically. We successfully tested it by following these steps:

1. Install Node.js first, if you haven’t done so already. Point your browser to the official Node.js download page and follow the instructions to get and run a prebuilt Node.js Installer or Binary.
2. To install the generator software, open a command line interface (CLI) on your computer and use your keyboard to type the npm install -g openapi-mcp-generator command, followed by the Enter key. When the installation is complete, you’ll see something like:

added 108 packages in 17s

35 packages are looking for funding
  run `npm fund` for details

Now that the generator software is installed, create one MCP server for each GM-X Auto API that the LLM application will utilize. For example, to create an MCP server for the GM-X Auto logon API:

3. Point your browser to the Geoprise GM-X Auto GitHub models page.
4. On the GM-X Auto GitHub models page, or at its left sidebar, browse for and click or tap the GMXAuto_logon.json link. The API documentation page appears for the logon API.
5. Near the upper right corner of the API documentation page, click the Download raw file button. The GMXAuto_logon.json file is copied to the Downloads folder on your computer.
6. Navigate to the Downloads folder on your computer, cut (or copy) the GMXAuto_logon.json file you downloaded at Step 5, above, and paste it into the folder you wish to use as your source document repository. This is the path/to/ folder at Step 8, below.
7. Create a new folder for the MCP server on your computer. This is the path/to/output/directory folder at Step 8, below.
8. In the CLI, use your keyboard to type the openapi-mcp-generator --input path/to/GMXAuto_logon.json --output path/to/output/directory command, followed by the Enter key. Substitute path/to/ and path/to/output/directory, respectively, with the paths to the folders described at Steps 6 and 7, above. In a split second, you’ll see the result illustrated in Figure 2, below.
9. Repeat Steps 3 through 8, above, for each additional GM-X Auto API that requires an MCP server.

Note that for obvious reasons it is mandatory to create an MCP server for the GM-X Auto logon API, unless you’ve configured your AI agents to use Amazon Web Services (AWS) application load balancer (ALB) authentication session cookies.

It is also mandatory to create a separate MCP server for the GM-X Auto menu API (GMXAuto_menu.json file), which provides access to all GM-X ERP functions, forms, and reports while strictly enforcing all role-based access controls that prevent AI agents from escaping and running wildly free.

Note also that our API bundles available at GitHub describe a reference implementation of the GM-X ERP application, not live sites. For MCP servers generated from those bundles to actually work, you must first modify the files you downloaded at Step 5, above, so Line 17 points to a real running server that hosts the GM-X ERP application. Lines 17 and 21 show exemplary uniform resource locators (URLs) for production using different authentication methods. Line 25 shows an exemplary URL for final staging QA, while Line 29 shows an exemplary URL for integrating testing and Line 33 shows an exemplary URL for development. As you can see in Figure 2, the MCP server generator uses the first URL (Line 17) by default.

Figure 2 – Automatic MCP Server Generation Using Open-Source openapi-mcp-generator

Alternatively, you can subscribe to various MCP generator services such as Postman, Speakeasy Gram, liblab, Prefect FastMCP, and Stainless. We successfully tested the Speakeasy Gram service for the GM-X Auto logon API by following these steps:

10. Point your browser to the Speakeasy service and log on to your Speakeasy account. The Speakeasy Dashboard screen appears.
11. On the Speakeasy Dashboard screen, in the PROJECTS section, search or browse for and then tap, or click, the project for which you wish to create the new MCP server. The Project Overview section appears on the Speakeasy Dashboard screen.
12. At the left sidebar of the Speakeasy Dashboard screen, select the MCP Gateway link. The MCP Servers section appears on the Speakeasy Dashboard screen.
13. Within the MCP Servers section on the Speakeasy Dashboard screen, tap or click the + Add new button. The Add MCP server screen appears.
14. In the Advanced section on the Add MCP server screen, click the Continue -> link in the From your API box. The Import OpenAPI specification screen appears.
15. Navigate to the path/to/ folder on your computer described at Step 6, above.
16. On the Import OpenAPI specification screen, drag and drop the GMXAuto_logon.json file into the box beneath the UPLOAD button of the Upload OpenAPI Specification section, which is activated by default. The name of this file appears by default (in lowercase) in the Name Your API text box below. Optionally, in the Name Your API text box, you can rename the API to your liking
17. Tap or click the CONTINUE button to the right of the Name Your API text box. The Speakeasy Gram service creates the MCP server and displays the Continue -> button in the Generate Tools section in a second or two.
18. In the Generate Tools section, tap or click Deployment details to view a log of the outcome. Figure 3, below, illustrates.
19. Tab or click the Continue -> button beneath the Deployment details. The MCP Servers section re-appears on the Speakeasy Dashboard screen displaying the new server you added at Steps 13-18, above.
20. Repeat Steps 13 through 19, above, for each additional GM-X Auto API that requires an MCP server.

Figure 3 – Automatic MCP Server Generation Using Speakeasy Gram Service

Both of the above examples prove that GM-X Auto API bundles can be input to MCP generators to create new MCP services without errors. Geoprise has produced all the production-ready OpenAPI specifications for the GM-X Auto ERP application, so you don’t have to.

To see for yourself, I invite you to visit our GitHub site, choose one or more models of greatest interest to you, and follow the steps I've set out here. There's no need to book any demos.

Additional Self-Hosting Configuration Steps

As you can see from the Figure 2, the self-hosting option requires you to complete a few additional configuration steps before AI agents can reach the new MCP servers. You’ll need to:

21. In the CLI, use your keyboard to type the npm install command, followed by the Enter key, to install the MCP server’s dependencies.
22. In the CLI, use your keyboard to type the npm run build command, followed by the Enter key, to generate TypeScript code for the MCP server.
23. In the CLI, use your keyboard to type the npm start command, followed by the Enter key, to start and run the MCP server.
24. Open the settings or desktop configuration file for your LLM application; for e.g., navigate to Settings -> Connectors -> Create for the ChatGPT Web or desktop client, or open the claude_desktop_config.json file for Claude Desktop.
25. Modify the settings or desktop configuration file you opened at Step 24, above, to insert the MCP server, and then re-save the settings or desktop configuration file.
26. Repeat Steps 21-25, above, for each additional GM-X Auto API that requires an MCP server.

Gotchas You Won't Have To Worry About When Deploying The GM-X Auto OpenAPI MCP Bridge

Riya Sethi, the Truto Software Engineer, doesn’t mince words in her blog post OpenAPI to MCP: How MCP Servers Auto-Generate Tools From API Docs:

If you are building AI agents that interact with external SaaS platforms, you have likely hit a wall. Manually writing and maintaining JSON Schema tool definitions for every API endpoint across dozens of providers is an unscalable architecture.

Why? Because:

Vendor APIs change constantly. Endpoints are deprecated, required fields shift, and documentation often lies. Hardcoding your AI agent's tools against these moving targets guarantees your engineering team will spend their cycles patching broken schemas instead of improving agent reasoning … Auto-generating MCP tools from OpenAPI specifications is not a simple parsing exercise. It is a solved problem in the trivial case and a hard problem at production quality.

Having done all that work, even if you successfully:

take a vendor's OpenAPI specification, run it through a script, and expose every single endpoint as an MCP tool [, such] naive 1:1 mapping fails in production immediately.

That’s because of “tool explosion” or “context bloat” which means:

A REST API with 200 endpoints becomes 200 tools. LLMs struggle with tool selection accuracy when presented with more than 25 to 50 tools at once. Frontier models degrade sharply once the tool list crosses a few dozen entries because every tool description competes for the same context budget and the router has to disambiguate more candidates per call. Ship all 200, dump an entire spec into an MCP server, and the agent starts guessing while wasting massive amounts of valuable context window space.

Every tool description you expose to an LLM costs tokens on every request. A 200-endpoint API shipped as 200 MCP tools burns 15-30k tokens before the model has read the user's message. Context bloat is not a rounding error; it is the dominant cost driver for agent workloads … Because LLMs degrade when exposed to more than 50 tools, you cannot serve a massive API surface on a single MCP endpoint. You must implement filtering. The fix is tool scoping. Group endpoints by functional area and let the MCP server owner select which groups to expose … Combined tag and method filters routinely cut a 200-tool provider dump down to 12-30 relevant tools per server, which is the sweet spot where models stop hallucinating tool names and context windows are preserved.

The GM-X Auto OpenAPI MCP Bridge documentation consists of 452 API bundles that expose a total of 7,870 endpoints, or 17 endpoints per API on average. This means only four of the APIs (less than one percent) expose more than 50 tools per MCP server, of which the largest (GMXAuto_invoice_header.json) ships with 87―far short of the 200-tool “dumps” that SaaS vendors tend to provide.

By contrast, 398 of the GM-X Auto API bundles (88 percent) ship with 30 or fewer tools per server, and those API bundles expose just 14 endpoints per API on average.

In short, the overwhelming majority of GM-X Auto API bundles fit well within the “sweet spot” that preserves context windows and avoids hallucinations, without requiring any additional filtering. Only the judicious selection of APIs to fit specific narrowly-scoped AI deployments is needed. 

Sethi mentions another important architectural aspect concerning “snake case,” the naming convention for objects, properties, and methods which replaces spaces with underscore (_) characters, and uses lowercase letters only:

LLMs handle get_single_hubspot_contact_by_id or create_a_crm_contact more reliably than getContact. The tool name doubles as a strong semantic hint about the operation. Names derived from the provider label plus resource plus method survive tokenization better and reduce hallucinated tool calls.

The good news is that nearly all objects and properties within the GM-X ERP application are natively identified using “snake case,” as our Programming Guidelines have strongly recommended for the past twenty years. Names that comply with those guidelines not only provide the optimal semantic hints for LLMs; they eliminate difficulties that LLMs encounter when trying to comprehend labels used in legacy ERP systems.

To illustrate, as shown in the GMXAuto_unit_of_measure_conv.json API, the GM-X object name is uom_conversion and one of its property names is conversion_factor. The name of the path which adds a new conversion factor is uom_conversion(add2) which is derived from the resource and method. Comparable names within the legacy SAP S/4HANA ERP system offer much weaker semantic hints for LLMs; for example, BAPI_MATERIAL_SAVEDATA (the method for adding a new conversion factor for material), BAPIMATMRM (unit of measure conversions object for material), UMREZ (conversion numerator), and UMREN (conversion denominator). 

Conclusion

In conclusion, the foregoing constitutes irrefutable proof that the GM-X Auto OpenAPI Bridge documentation can genererate working Model Context Protocol (MCP) servers automatically, without the explosion of tools, context bloat, or token consumption waste that plagues APIs provided by vendors of most ERP applications, including Software-as-a-Service (SaaS) as well as legacy ERP APIs.