home / mcp / openapi mcp server

OpenAPI MCP Server

Basic and simple openapi spec to mcp app (demo only)

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aaker-mini-openapi-mcp": {
      "url": "http://localhost:3000/message",
      "headers": {
        "OPENAPI_BASE_URL": "https://api.example.com (base URL used for API requests)",
        "OPENAPI_BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

You can turn an OpenAPI 3.x specification into a ready-to-use MCP server that lets Large Language Models interact with REST APIs through a standardized tool interface. This server automates tool generation from your API spec, handles authentication, parameter validation, and error reporting, and supports both local stdio and remote HTTP transports for flexible integration with MCP clients.

How to use

Set up the MCP server to expose your OpenAPI specification as MCP tools, then connect your MCP client to those tools. You will run a local stdio instance for direct integration with a client on the same machine or start an HTTP server to accept remote requests. Use the provided commands to validate your spec, start the server, or connect via HTTP transport.

How to install

Prerequisites: install Node.js (with npm) on your machine.

# Install dependencies
npm install

# Validate your OpenAPI specification
node src/index.js validate -s UserQueueList.json

# Start the MCP server with a local OpenAPI spec and base URL
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t your-bearer-token

Configuration and usage details

Environment variables can be used as an alternative to command-line arguments. For example, define the base URL and bearer token, then start the server with the same command as above.

Troubleshooting

If you encounter issues such as missing tools or authentication failures, ensure your OpenAPI spec is valid, the security schemes include a bearer token, and that you pass correct token values. Increase timeout if you experience network delays and check that the API endpoint is reachable.

Configuration examples

{
  "mcpServers": {
    "openapi_stdio": {
      "command": "node",
      "args": [
        "src/index.js",
        "serve",
        "-s", "UserQueueList.json",
        "-b", "https://your-api-domain.com",
        "-t", "your-bearer-token"
      ]
    }
  }
}

Transport options

Stdio transport is the default and runs locally with standard input/output streams, ideal for direct integrations. HTTP transport exposes an HTTP server that can be reached remotely, enabling debugging and broader MCP client access.

Examples of how tools are exposed

The server converts OpenAPI operations into MCP tools. For example, a GET operation can become a tool like ListUsers, and another GET operation can become ListCallqueues, each with an input schema that reflects required and optional parameters.

Starting via HTTP transport example

{
  "mcpServers": {
    "openapi_http": {
      "url": "http://localhost:3000/message"
    }
  }
}
```

```bash
node src/index.js serve -s UserQueueList.json --transport http --http-port 3000

Available tools

ListUsers

Tool to list basic user information in a domain, derived from GET /domains/{domain}/users/list

ListCallqueues

Tool to read basic information on call queues in a domain, derived from GET /domains/{domain}/callqueues/list