MCP

Introduction

Orval generates MCP server from OpenAPI. Model Context Protocol (MCP) server create great value by simply relaying API clients. This eliminates the need to wait for someone to develop it or publish it on the marketplace. You can create an MCP server with various services that you have OpenAPI for yourself and use them with AI agents. And from a single OpenAPI specification, various API ecosystem components can be generated. The same specification can be used to support both traditional client-server applications and AI agent integration.

How to use

If you want to generate a server of Model Context Protocol (MCP), define the client property to mcp and a server of MCP will be generated in the target file and directory. You can check typescript-sdk.

Example with orval.config.js

1 import { defineConfig } from 'orval';
2 
3 export default defineConfig({
4   petstore: {
5     input: {
6       target: './petstore.yaml',
7     },
8     output: {
9       mode: 'single',
10       client: 'mcp',
11       baseUrl: 'https://petstore3.swagger.io/api/v3',
12       target: 'src/handlers.ts',
13       schemas: 'src/http-schemas',
14     },
15   },
16 });

Currently, Please note that the mcp client only works in single mode.

Generated Template Structure

orval generates files in the following structure:

1 src/
2 ├── http-schemas
3 │   ├── createPetsBodyItem.ts
4 │   ├── error.ts
5 │   ├── index.ts
6 │   ├── listPetsParams.ts
7 │   ├── pet.ts
8 │   ├── pets.ts
9 │   └── updatePetByParamsParams.ts
10 ├── handlers.ts
11 ├── http-client.ts
12 ├── server.ts
13 └── tool-schemas.zod.ts

Each generated file serves a specific purpose:

• http-schemas/: Directory containing TypeScript type definitions for request/response data
• handlers.ts: Contains handler functions that use the fetch client to make API calls and return results in MCP format
• http-client.ts: Contains generated fetch client functions for API communication
• server.ts: Defines MCP tools and server configurations
• tool-schemas.zod.ts: Defines Zod schemas for MCP tool inputs

Using the generated MCP Server

To use the generated code as an MCP server, follow these steps:

1. Build the Docker image:

 docker build ./ -t mcp-petstore

2. Configure the MCP server in your AI agent's configuration:

Here we will introduce the settings using the cline for the ai agent. It will work with other ai agents, so please adjust the detailed settings accordingly. For clile, specify as follows:

1 {
2   "mcpServers": {
3     "petstore": {
4       "command": "docker",
5       "args": [
6         "run",
7         "-i",
8         "--rm",
9         "mcp-petstore"
10       ],
11       "disabled": false,
12       "alwaysAllow": []
13     },
14   }
15 }

This setup allows your AI agent to interact with the petstore API through the MCP protocol, using the generated handlers and tools.

Checkout here for the full example.