How to Turn Swagger into an MCP Server

Swagger already contains most of an MCP tool contract

If your REST API has Swagger documentation, you probably already have the information an AI client needs to use it: paths, HTTP methods, parameters, request bodies, response schemas, and descriptions.

The missing piece is a runtime that presents that contract through MCP and safely forwards approved calls to the original API.

datamcp can connect an OpenAPI 3.x document or a supported Swagger UI or Redoc page, expose a remote MCP endpoint, attach a configured upstream credential server-side, and restrict an MCP link to read-only HTTP methods when needed.

It does not generate a separate MCP tool for every operation. The current OpenAPI integration exposes four focused tools:

• list_api_endpoints lists the operations found in the specification
• get_endpoint_details returns parameters, request-body information, and responses for one operation
• get_api_schema returns component schemas
• call_endpoint calls a selected live endpoint with path, query, header, and body values

That smaller tool surface lets the AI discover the API before choosing an operation, instead of loading hundreds of endpoint-specific tools into the client's context.

This guide walks through the complete setup without generating or deploying a new server project.

Swagger vs OpenAPI: which URL do you need?

The terms are often used interchangeably, but they are not exactly the same.

OpenAPI is the machine-readable specification format. It describes API paths and operations, inputs, outputs, servers, and security schemes in JSON or YAML.

Swagger is a tool ecosystem around OpenAPI. Swagger UI renders an OpenAPI document as interactive documentation. A page at /docs or /swagger is usually HTML that loads the underlying specification from another URL such as /openapi.json.

datamcp accepts:

1. a public HTTPS URL for a raw OpenAPI 3.x JSON document
2. a public HTTPS URL for a raw OpenAPI 3.x YAML document
3. a supported Swagger UI or Redoc documentation page from which the embedded specification can be detected

A raw specification URL is the most reliable option. Documentation pages differ in how they embed or load their specs, so extraction is attempted when the page exposes enough information.

Before you start

You need:

• an existing REST API
• an OpenAPI 3.x document or supported documentation page available over public HTTPS
• a supported upstream credential if live API calls require one
• a datamcp account
• an MCP client that supports the remote endpoint and authentication method you plan to use

The specification URL itself must be publicly fetchable. Current OpenAPI connection authentication applies to calls against the API, not to downloading a private specification.

For a first test, use an API or environment where read-only calls are safe and results contain no sensitive production data.

Step 1: Find your OpenAPI source

Start with the documentation URL your team already uses. Common locations include:

https://api.example.com/docs
https://api.example.com/swagger
https://api.example.com/api-docs
https://api.example.com/openapi.json
https://api.example.com/openapi.yaml

If you have Swagger UI, the page often references the real definition through its url, configUrl, or embedded spec configuration. Swagger's official UI configuration supports all three patterns, which is why two visually similar documentation pages may expose the source differently.

Prefer the raw JSON or YAML URL when you can find it. Use the documentation page when the source URL is not obvious and datamcp can extract it.

Step 2: Check the specification

Before connecting it, inspect the document for the fields that affect tool quality and request execution.

At minimum, verify:

• the root openapi value identifies a 3.x specification
• servers points to the correct API base URL
• paths contains the operations you want the AI to use
• path parameters such as /users/{id} are declared correctly
• required query, header, and body inputs are marked as required
• operation summaries and descriptions explain intent clearly
• component schemas describe reusable request and response models
• securitySchemes reflects the API's authentication contract

For example:

openapi: 3.0.3
info:
  title: Customer API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /customers/{id}:
    get:
      summary: Get one customer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Customer found

Descriptions matter. An AI client can only choose an operation safely when the specification explains what the operation does and what its inputs mean.

Step 3: Create the OpenAPI connection

In datamcp:

1. Open Connections.
2. Select New Connection.
3. Choose OpenAPI.
4. Give the connection a recognizable name.
5. Paste the raw OpenAPI URL or supported Swagger UI or Redoc URL.
6. Run validation.

datamcp checks that it can fetch and parse the source, identifies the API version, and counts the available operations. If validation fails, fix the source before creating an MCP link; the MCP layer cannot compensate for an inaccessible or invalid specification.

Step 4: Configure upstream authentication

Current OpenAPI connections support these choices for calls to the original API:

None

Use this for public endpoints that require no credential.

API key

Store a key and choose the location declared by the specification: request header, query string, or cookie. You also choose the parameter name, such as X-API-Key, api_key, or session_key.

Bearer token

Store a token that datamcp sends as:

Authorization: Bearer YOUR_TOKEN

The configured credential stays on the datamcp side and is attached to approved calls. It does not need to be copied into the AI client's MCP configuration.

Basic auth

Store a username and password for APIs that use HTTP Basic authentication. datamcp creates the Authorization: Basic ... header server-side.

Custom headers

Add optional fixed headers when an API requires tenant, version, or gateway values in addition to its primary credential.

Do not describe this as automatic support for every OpenAPI security scheme. Upstream OAuth authorization flows, automatic token refresh, mutual TLS, and authentication for private specification URLs are not part of the current public connection workflow. A pre-issued Bearer token can be stored, but datamcp does not obtain or refresh it from the upstream identity provider.

Step 5: Create an MCP link

Once the OpenAPI connection exists, create an MCP link and choose its access mode.

Read Only

Read Only permits GET and HEAD calls. Methods that normally change state, including POST, PUT, PATCH, and DELETE, are blocked by the OpenAPI executor.

Use Read Only for:

• production exploration
• shared integrations
• analytics and support workflows
• the first connection to an unfamiliar API

Full Access

Full Access allows the MCP client to call the methods available in the connected specification, including write methods. The upstream API still applies its own authorization rules.

Use Full Access only when the workflow genuinely needs writes and the configured upstream credential has the minimum required permissions.

Step 6: Connect and test a client

Open the MCP link's setup guide and copy the remote endpoint configuration for your client.

After the client connects, test the integration in this order:

1. Ask it to list the API endpoints.
2. Ask it to inspect one specific GET operation.
3. Confirm the required path and query parameters.
4. Call that endpoint with a harmless input.
5. Review the result in the client and confirm execution in the upstream API or infrastructure logs.

A useful first prompt is:

List the available API endpoints. Do not call anything yet.
Group them by resource and mark which methods can change data.

Then narrow the request:

Inspect GET /customers/{id}. Explain every required parameter,
then ask me for any missing value before calling it.

This encourages discovery before execution and makes mistakes easier to catch.

How a live API call is assembled

When the client invokes call_endpoint, it identifies the HTTP method and exact path template from the specification. It can also provide:

• path_params for placeholders such as {id}
• query values
• additional declared headers
• a request body for operations that accept one

datamcp verifies that the endpoint exists in the connected specification, blocks write methods on a Read Only link, checks required parameters, resolves the server URL, injects the configured credential, sends the request, and returns the response through MCP.

The path must match the specification template. For example, use /customers/{id} plus a path parameter rather than inventing /customers/123 as the operation identifier.

What datamcp does not generate

This workflow is intentionally different from a code generator.

datamcp does not create:

• a repository containing a custom MCP server
• one MCP tool definition per OpenAPI operation
• deployment manifests for your own infrastructure
• upstream OAuth consent or token-refresh flows
• new business logic beyond what the REST API already implements

It hosts a stable MCP layer that can discover the connected OpenAPI contract and forward approved calls at runtime.

Choose generated code instead when you need custom transformations, multi-step domain workflows, nonstandard authentication, private-network deployment, or complete control over the MCP server implementation. Use the OpenAPI to MCP vs custom MCP server comparison to evaluate that boundary before committing to either architecture.

Troubleshooting

The specification cannot be fetched

Confirm that the URL is public, uses HTTPS, and returns the document without browser-only authentication. If you supplied a documentation page, try the raw JSON or YAML source instead.

The wrong API base URL is used

Check the OpenAPI servers field. A correct list of paths is not enough if the specification points to localhost, staging, or a relative URL that does not resolve as expected.

An endpoint is missing

Verify that the operation exists under paths, uses a standard supported HTTP method, and appears in the exact document datamcp fetched. Then resync the connection after updating the specification.

A call returns 401 or 403

Confirm that the connection uses the correct auth type, key location, and parameter name. For Basic auth, verify the username and password; for Bearer auth, confirm the token is still valid and has permission to call that operation.

A write call is blocked

Check the MCP link mode. Read Only deliberately permits only GET and HEAD. Create a separate Full Access link only if the client must perform writes.

A required input is reported missing

Inspect the endpoint details and provide the required path, query, header, or body value. If the requirement is absent from the specification, fix the OpenAPI document so every client receives the same contract.

Production checklist

Before connecting a production API:

• start with a Read Only MCP link
• use a dedicated upstream credential with least privilege
• remove undocumented write operations from the exposed specification
• write clear operation and parameter descriptions
• verify the servers URL and environment
• test required parameters and error responses
• review activity after the first calls
• create separate links for different clients or access levels
• revoke or rotate the upstream credential when its scope changes

The OpenAPI document is now part of your AI access boundary. Treat changes to operations, descriptions, and security schemes as production changes.

Next steps

Review the OpenAPI to MCP product page for the hosted architecture, use the OpenAPI connection documentation for the current setup reference, and read the MCP gateway guide to understand authentication, access policy, credentials, revocation, and the different PostgreSQL and OpenAPI logging boundaries.

You can start with one OpenAPI connection and one MCP link on the free plan. No generated server project is required.

For the underlying standards, see the official OpenAPI 3.1 specification, Swagger explanation of OpenAPI, and MCP server tools documentation.