← Back to blog/Guides

OpenAPI to MCP: Turn One API Workflow Into a Useful Tool

Start with one approved API operation, not every endpoint. A runnable local example shows the mapping, input checks and the administrative operation that stays out.

F
Faizan Khan
• 9 min read

OpenAPI can describe your API. It does not decide which parts an assistant should use. A useful OpenAPI-to-MCP workflow starts with a task, selects the necessary operation, maps its inputs and checks the result. It does not automatically expose the entire specification.

For a support team, that task might be checking a documented export limit. It probably does not include creating an administrator key, even if both operations exist in the same API description.

This guide walks through that distinction with a small example you can run locally. The example uses synthetic public-plan data, makes no network requests and needs no credentials. It is a deliberate mapping of one operation, not a general-purpose OpenAPI converter or a production authorization implementation.

If you are still choosing the interface, start with MCP vs API. If the question is who should operate the endpoint, use the MCP hosting guide.

What changes between OpenAPI and MCP?

An OpenAPI description describes an HTTP API: paths, operations, parameters, responses and security requirements. An MCP server exposes capabilities to compatible clients through a different protocol.

OpenAPI describesThe MCP mapping needs to decide
A method and pathWhether that operation belongs in this agent workflow
An operation ID and summaryA useful tool name and an accurate description
Path, query and body parametersA bounded input schema and a controlled request mapping
Response schemasWhat the tool returns and how the client can validate it
Security schemes and requirementsHow the real caller is authenticated and authorized
Several unrelated API areasWhich operations remain unavailable to this client

The MCP tools specification defines the tool interface. Your application still owns its business rules. An operation appearing in a description is not permission for an agent to call it.

An MCP client uses a deliberately scoped server to retrieve an approved source

Download the runnable example

Download the three-file example bundle and extract it into a new folder. You can inspect the same files individually:

The example.com URLs are reserved examples, not live endpoints. The limits are illustrative values, not DocsAlot pricing, customer records or a customer's actual product limits.

1. Choose the support task before selecting operations

Write the job in the user's words: "What is the export limit on the Team plan?" That is a public product-information lookup. The answer should identify the plan, return the right limit and include the approved source.

Our example specification also contains POST /v1/admin/keys. That operation has no place in this lookup. It remains in the specification to make the exclusion visible, not because the example implements key creation.

Use an explicit operation allowlist. Selecting every GET operation is not an equivalent control: a read endpoint can still expose private records or an unrestricted export. Select for the workflow, source and caller, not only the HTTP method.

For an initial proof, one operation is enough. If a support teammate needs a policy explanation rather than current account data, a documentation MCP may be the simpler source.

2. Inspect the inputs and response you already describe

The selected operation in the downloadable specification is:

YAML
1/v1/public/plans/{planId}:
2 get:
3 operationId: getPublicPlan
4 summary: Read the documented export limit for a public plan.
5 security: []
6 parameters:
7 - name: planId
8 in: path
9 required: true
10 schema:
11 type: string
12 enum: [starter, team]

This is an excerpt, not the full OpenAPI document. The download includes responses, a reusable response schema and the excluded administrative operation.

There are only two accepted plan identifiers. The response has three fields: planId, maxExportRows and sourceUrl. That is a small contract a support workflow can check, instead of interpreting an arbitrary API payload.

If your real description has unresolved references, missing required fields or examples that contradict the response, repair those first. Generating another interface around an unclear contract does not remove the ambiguity.

3. Map only the approved operation

The sample reads the specification and selects getPublicPlan explicitly. It stops at startup if that operation is renamed, its declared public security requirement changes, or its enum no longer matches the two implemented fixtures.

It then registers a tool called get_public_plan. The important mapping is compact:

JavaScript
1server.registerTool(
2 "get_public_plan",
3 {
4 description: operation.summary,
5 inputSchema: z.object({ planId: z.enum(planIds) }),
6 outputSchema: z.object({
7 planId: z.enum(planIds),
8 maxExportRows: z.number().int().positive(),
9 sourceUrl: z.url(),
10 }),
11 annotations: {
12 readOnlyHint: true,
13 destructiveHint: false,
14 idempotentHint: true,
15 openWorldHint: false,
16 },
17 },
18 handler
19);

This excerpt depends on the imports, approved operation, fixture data and handler in the downloadable server. Use that complete file for the local run.

The read-only annotation is a hint to clients, not an authorization system. In this example, the actual boundary is simpler: the handler can only return fixed synthetic data. There is no HTTP request, account credential or administrative handler to invoke.

This intentionally narrow mapping does not resolve arbitrary references, translate every OpenAPI schema, handle pagination or generate a complete API client. A general converter needs broader coverage and tests; an SDK is another output with a different job.

4. Run the local version

The sample follows the TypeScript SDK v2 server API, but its file contains plain JavaScript. In the folder containing the extracted example:

Bash
1npm init -y
2npm install @modelcontextprotocol/server@2.4.0 zod@4.6.7
3node server.mjs

The process speaks MCP over stdio. It does not open a browser, listen on an HTTP port or print a normal interactive prompt. A compatible local MCP client should launch Node with the absolute path to server.mjs; stop a directly launched process with Ctrl+C.

Ask the client to discover the tools. There should be exactly one: get_public_plan. Then call it with planId: "team".

The synthetic result is:

JSON
1{
2 "planId": "team",
3 "maxExportRows": 10000,
4 "sourceUrl": "https://docs.example.com/plans/team"
5}

The handler returns both structured content and a text representation. Neither contains a customer record or a secret. The source URL demonstrates the contract; it is not a page the example fetches.

5. Check what stays unavailable

We ran the downloadable files locally on November 20, 2026 with Node 22.23.2, MCP server/client SDK 2.4.0 and Zod 4.6.7. The test record includes the file hashes and the checks performed.

Check performedObserved local result
Validate the complete OpenAPI 3.1 documentPassed with Swagger Parser 13.1.0; external references disabled
Discover the exposed toolsOnly get_public_plan; no admin/key operation
Request the synthetic Starter planStructured and text results agree on 1,000 rows
Request the synthetic Team planStructured and text results agree on 10,000 rows
Request an unsupported planRejected
Supply a path-like plan identifierRejected by the enum
Supply an empty plan identifierRejected
Rename the selected operation, change its security or expand its plan enumEach altered fixture stopped at startup

These are tests of a small local mapping. They are not evidence of HTTP hosting, OAuth correctness, private-data isolation, real API behavior or model answer quality. Returning a correct fixture is not the same as safely operating a customer's account.

For a live support workflow, also test a missing answer, an unavailable source and a released change. Our MCP evaluation worksheet separates those checks.

6. Replace the fixture carefully, not automatically

A production handler might call your existing API rather than returning fixtures. Keep that destination controlled by server configuration; do not let a model supply an arbitrary upstream URL or an authorization header.

Before adding private data, define the authenticated caller and the application-level permissions. A model-supplied workspace ID or plan ID is an input, not proof of access. Follow the MCP authorization guidance for the remote protocol and enforce the underlying product's rules as well.

The production work also includes timeouts, rate limits, safe error responses, appropriately limited logs and a way to revoke access. Do not record credentials or full customer payloads simply because logging makes the prototype easier to debug.

Keep write operations separate until there is an explicit workflow and approval policy for them. A support lookup should not silently acquire billing, deletion or administrative powers during a generator update.

Do you need API actions, or product knowledge?

Those are different projects. Live account status may need a permitted API operation. Setup instructions, product limits, policies and troubleshooting guidance may already have an approved home in documentation.

DocsAlot can connect a published documentation workflow to a hosted MCP surface, alongside the human-readable site and other agent-facing outputs. If that is your goal, request a hosted documentation MCP first version from public product context. Scope transactional API operations and private authorization separately rather than assuming they are included in a documentation endpoint.

For the wider choice, use the server shortlist. To operate a custom remote service, follow the implementation checklist and hosting decision guide.

Common questions

Can we keep our existing API?

Yes. The MCP layer can call the same underlying service while exposing a narrower workflow to compatible clients. You do not have to replace ordinary API integrations or generated SDKs.

Does an OpenAPI security scheme configure MCP authorization?

No. It describes requirements of the API, not a complete identity and consent flow for the MCP endpoint. Validate both the remote connection and the permissions enforced by the underlying application.

Is this a no-code OpenAPI-to-MCP generator?

No. It is a runnable, deliberately limited mapping so the design choices and tests are visible. Use a generator or a managed service when it fits, but evaluate its actual operation coverage, deployment responsibilities and access model before using it with production data.

Continue This Guide