What is OpenAPI MCP Server?
The OpenAPI MCP Server feature allows you to automatically create an MCP server from any existing OpenAPI (Swagger) specification. Instead of manually coding an MCP server to expose your API endpoints, TrueFoundry parses your OpenAPI spec and generates tools for each endpoint automatically. This is particularly useful when you want to:- Quickly expose existing REST APIs as MCP tools for AI agents
- Avoid duplicating API definitions between your backend and MCP server
- Quickly create a POC for development
How It Works
When you provide an OpenAPI specification, TrueFoundry:- Parses the OpenAPI spec to extract all available endpoints, their parameters, request bodies, and response schemas
- Generates MCP tools for each endpoint with appropriate input schemas derived from the OpenAPI definition
- Creates a OpenAPI MCP server that proxies requests to your actual API endpoints
- Handles authentication based on the security schemes defined in your OpenAPI spec
| OpenAPI Element | MCP Mapping | Notes |
|---|---|---|
operationId | Tool name | Uses operationId if present; otherwise generates a name |
summary / description | Tool description | Uses summary if available, falls back to description |
parameters + requestBody | Tool inputSchema | Combined into a single input schema |
responses | Tool outputSchema | Response schema |
Create an OpenAPI MCP Server
Follow the interactive demo below to create and configure an MCP server from your OpenAPI specification:Navigate to MCP Servers
Go to the MCP Servers tab in the TrueFoundry AI Gateway and click Add Server.
Select OpenAPI Source
Click From OpenAPI spec. You can provide your OpenAPI specification in one of the following ways:
| Method | Description |
|---|---|
| URL | Provide a publicly accessible URL to your OpenAPI JSON or YAML file |
| Paste Content | Paste the raw OpenAPI specification content |
Select Tools and Configure
After providing the OpenAPI spec, select the tools you want to expose. For each tool, you can configure:
| Field | Description |
|---|---|
| Tool Name | The name used to call the tool (defaults to operationId from the spec) |
| Tool Description | A description to help AI agents understand when to use this tool |
Configure Server Details
Provide the following configuration for your OpenAPI MCP Server:
| Field | Description |
|---|---|
| Name | A descriptive name for the MCP server (e.g., my-api-server) |
| Description | A brief description of what this MCP server provides |
| OpenAPI Server URL | The base URL of your API server where requests will be proxied |
Configure Authentication and Access Controls
Set up authentication based on how your API is secured. See MCP Gateway Auth & Security for detailed authentication options and Access Control for managing permissions.
Frequently Asked Questions
What OpenAPI versions are supported?
What OpenAPI versions are supported?
TrueFoundry supports OpenAPI 3.0 and 3.1 specifications.
Can I update the OpenAPI spec after creation?
Can I update the OpenAPI spec after creation?
Yes, you can update the OpenAPI specification at any time. Navigate to the MCP server settings and upload a new spec or update the URL. Tools will be regenerated based on the updated specification.
What happens if my API returns errors?
What happens if my API returns errors?
API errors are passed through to the AI agent as tool execution failures. The error response body and status code are included in the error message, allowing the agent to handle or report the error appropriately.
Does this work with authenticated APIs?
Does this work with authenticated APIs?
Yes. Configure the appropriate authentication method when creating the MCP server. The gateway handles injecting authentication headers or tokens into every request made to your API.
Can I combine OpenAPI MCP Server with Virtual MCP Server?
Can I combine OpenAPI MCP Server with Virtual MCP Server?
Yes. Once your OpenAPI MCP Server is created, you can include its tools in a Virtual MCP Server to create curated tool collections that combine endpoints from multiple APIs.
Best Practices
Use Descriptive Operation IDs
Ensure your OpenAPI spec has clear
operationId values as these become tool names that AI agents use.Document Parameters Well
Include detailed descriptions for all parameters as this helps AI agents understand when and how to use each tool.
Secure Sensitive Endpoints
Use endpoint filtering to exclude administrative or destructive operations from the MCP server.