MCP Server Generator

What is an MCP server generator

An MCP server generator creates servers that follow the Model Context Protocol from existing API definitions. These servers act as translators between AI models and your API, converting natural language requests into structured API calls.

The generator reads your OpenAPI specification (the formal description of your API) and produces a server that exposes each endpoint as a tool. When an AI assistant wants to use your API, it sends a request to this server following the MCP format, and the server handles the translation to your actual API.

• Automation benefit: Instead of manually coding the translation layer, the generator builds it automatically.

• Standardization: The generated server follows the MCP specification, ensuring compatibility with AI tools.

• API reuse: Your existing API remains unchanged while becoming accessible to AI assistants.

For example, if your API has an endpoint to create users, the MCP server exposes a "create user" tool that AI models can understand and invoke when a user asks to "create a new account."

How to build MCP servers from an OpenAPI specification

Building an MCP server from your OpenAPI spec involves a few key steps. Here's how we approach it at Stainless:

1. Prepare your OpenAPI file

Start with a valid OpenAPI specification that accurately describes your API. The more detailed your spec, the better the generated MCP server will be. Make sure it includes:

• Complete endpoint definitions

• Parameter descriptions

• Request and response schemas

• Authentication requirements

If your spec has issues, tools like Swagger Editor can help identify and fix them before generation.

2. Generate the server code

Use an MCP server generator to create the base project. With Stainless, you can run:

stainless mcp generate --openapi ./openapi.yaml --output

This creates a new directory with all the necessary files to run an MCP server, including:

• Server code (typically Node.js or Python)

• Configuration files

• Environment variable templates

3. Configure authentication and endpoints

Edit the generated configuration to set up authentication and customize endpoint behavior. This usually involves:

• Setting API keys or OAuth credentials

• Enabling or disabling specific endpoints

• Configuring rate limits or other behaviors

For example, a simple configuration might look like:

auth:
  type: apiKey
  in: header
  name: X-API-Key
endpoints:
  /users:
    enabled: true

4. Test with AI assistants

Run your MCP server and test it with AI assistants like Claude or GPT. Ask the AI to perform tasks that use your API and verify that:

• The AI correctly understands the available tools

• Requests are properly translated to API calls

• Responses come back as expected

Testing helps identify any issues with schema translation or authentication that need adjustment.

Hello world example

In a simple case, this OpenAPI spec:

paths:
  /hello:
    get:
      summary: Say hello
      parameters:
        - name: name
          in: query
          schema:
            type: string
      responses:
        200:
          description: A greeting
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type

Would be transformed into this MCP Tool:

{
  "name": "sayHello",
  "description": "Say hello",
  "input_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      }
    }
  }
}

When an AI assistant uses this tool with input {"name": "World"}, the MCP server translates it to a GET request to /hello?name=World on your API.

OpenAPI endpoints don't perfectly map to tools

While both MCP tools and OpenAPI specs use JSON Schema, you can't just copy them over as-is. You have to combine the request body, path parameters, query parameters, and header parameters all into one schema, and handle any naming collisions automatically.

For example, an OpenAPI endpoint might have:

• A path parameter called id

• A query parameter also called id

• A request body with an id field

In the MCP tool schema, these need to be renamed to avoid conflicts, perhaps as pathId, queryId, and bodyId.

Another challenge is that OpenAPI endpoints often have different operations (GET, POST, PUT, DELETE) on the same path. Each of these needs to become a separate tool in the MCP server, with names that clearly distinguish their purpose.

• Schema transformation: The generator must intelligently merge and transform schemas.

• Naming strategy: Clear naming conventions help avoid conflicts and confusion.

• Documentation mapping: Original descriptions should be preserved for AI understanding.

Handle $refs and recursive references

OpenAPI schemas use $ref to point to chunks of reusable schema elsewhere in the file. However, MCP Tool schemas must be completely self-contained, meaning they cannot reference anything outside themselves.

This requires the generator to:

1. Find all $ref references in the schema

2. Resolve them by copying the referenced schema inline

3. Handle circular references to prevent infinite loops

For example, if you have a "User" schema that references an "Address" schema, the MCP tool schema needs to include the full Address definition within the User schema.

Recursive references (like a Comment schema that contains replies which are also Comments) need special handling to avoid infinite expansion. The generator typically sets a maximum depth for resolving recursive references.

# Original OpenAPI with $refs
Comment:
  type: object
  properties:
    text:
      type: string
    replies:
      type: array
      items:
        $ref: '#/components/schemas/Comment'

// MCP Tool schema with resolved references
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string"
    },
    "replies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "replies": {
            "type": "array",
            "items": {
              // Limited recursion depth
            }
          }
        }
      }
    }
  }
}

Many APIs have too many endpoints to be imported at once

MCP currently works by loading all of the tool schemas for an MCP Server at once into its context. The LLM then chooses which tool to use based on your request.

This approach works well for APIs with a reasonable number of endpoints. But many real-world APIs have hundreds of endpoints, which creates problems:

• AI models have context window limitations (the amount of text they can process at once)

• Too many tools overwhelm the model and reduce its ability to choose correctly

• Large schemas consume memory and slow down processing

For example, an e-commerce API might have endpoints for products, orders, customers, shipping, payments, and more. Loading all these at once could exceed the AI's context window.

MCP clients have different schema limitations

One of the harder issues was dealing with different clients. Claude Desktop handles the MCP protocol pretty well, but it turns out that JSON Schemas are interpreted differently between various AI models and MCP clients today, and have different limitations.

Some common differences include:

• Schema complexity: Some clients struggle with deeply nested objects or arrays

• Validation rules: Support for formats, patterns, and constraints varies

• Error handling: How schema validation errors are reported differs

• Size limits: Maximum schema size varies by client

For example, one client might handle a complex nested object with many properties, while another might need a flattened version with simpler types.

To address these differences, MCP server generators often include options to adjust schema complexity based on the target client, or implement runtime detection and adaptation.

Getting started with Stainless MCP server generator

At Stainless, we've built our MCP server generator to handle these challenges automatically. Our approach focuses on:

1. Intelligent schema transformation that preserves semantics while ensuring compatibility

2. Smart handling of references and recursive structures

3. Options for both static and dynamic tool loading

4. Client-aware schema generation

Getting started is simple:

1. Sign up at app.stainless.com/signup

2. Upload your OpenAPI specification

3. Configure authentication and other options

4. Download and run your generated MCP server

Our generator builds on our experience creating SDKs across multiple languages, applying the same principles of idiomatic code and developer experience to MCP servers.

Frequently asked questions about MCP server generators

What performance impact does an MCP server have?

An MCP server adds a small processing layer that typically adds 50-100ms to request times. This is negligible for most applications, especially considering the time AI models take to generate responses.

Do I need to modify my existing API to use an MCP server?

No modifications to your existing API are needed. The MCP server acts as a translation layer between AI assistants and your API, using your OpenAPI specification to understand how to map between them.

How are authentication credentials handled securely?

MCP servers typically store credentials in environment variables or secure credential stores, not in the code itself. They can also support passing through user credentials when the AI is acting on behalf of a specific user.