Openapi To MCP

1[![.NET Build](https://github.com/ouvreboite/openapi-to-mcp/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/ouvreboite/openapi-to-mcp/actions/workflows/build_and_test.yml)
2[![NuGet](https://img.shields.io/nuget/dt/openapi-to-mcp?logo=nuget&label=NuGet&)](https://www.nuget.org/packages/openapi-to-mcp)
3 
4# openapi-to-mcp
5 
6Use your OpenAPI specification to expose your API's endpoints as strongly typed tools.
7 
8Basic example for https://petstore3.swagger.io/ 🎉
9 
10```json
11{
12  "mcpServers": {
13    "petstore": {
14      "command": "openapi-to-mcp",
15        "args": [
16          "https://petstore3.swagger.io/api/v3/openapi.json"
17        ]
18    }
19  }
20}
21```
22 
23More complex example, using Github's API:
24```
25{
26    "mcpServers": {
27        "github": {
28            "command": "openapi-to-mcp",
29            "args": [
30                "https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions/api.github.com/api.github.com.yaml",
31                "--bearer-token",
32                "github_pat_xxxxxx",
33                "--tool-naming-strategy",
34                "verbandpath"
35            ]
36        }
37    }
38}
39```
40 
41This example use the bearer token auth (with a Github [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)) and force the tool naming strategy to "verb and path", as Github's operation ids are not valid tool names.
42 
43![Github demo](github_demo.gif)
44 
45## Install
46 
47As a Nuget tool: [openapi-to-mcp](https://www.nuget.org/packages/openapi-to-mcp)
48```sh
49dotnet tool install --global openapi-to-mcp
50```
51Or download the executables from the [releases](https://github.com/ouvreboite/openapi-to-mcp/releases)
52 
53## Usage
54 
55 
56```bash
57Usage:
58  openapi-to-mcp <open-api> [options]
59 
60Arguments:
61  <open-api>  You OpenAPI specification (URL or file) [required]
62 
63Options:
64  -t, --tool-naming-strategy <extension|extension_or_operationid_or_verbandpath|operationid|verbandpath>  How the tool name should be computed [default: extension_or_operationid_or_verbandpath]
65  -h, --host-override                                                                                     Host override
66  -b, --bearer-token                                                                                      Bearer token
67  -o2, --oauth-2-grant-type <client_credentials|password|refresh_token>                                   OAuth2 flow to be used
68  -o2_tu, --oauth-2-token-url                                                                             OAuth2 token endpoint URL (override the one defined in your OpenAPI for your chosen OAuth2 flow)
69  -o2_ci, --oauth-2-client-id                                                                             OAuth2 client id (for the client_credentials grant_type)
70  -o2_cs, --oauth-2-client-secret                                                                         OAuth2 client secret (for the client_credentials grant_type)
71  -o2_rt, --oauth-2-refresh-token                                                                         OAuth2 refresh token (for the refresh_token grant_type)
72  -o2_un, --oauth-2-username                                                                              OAuth2 username (for the password grant_type)
73  -o2_pw, --oauth-2-password                                                                              OAuth2 password (for the password grant_type)
74  -i, --instructions                                                                                      MCP instruction to be advertised by the server
75  --verbose                                                                                               Log more info (in sdterr) [default: False]
76  -?, -h, --help                                                                                          Show help and usage information
77  --version                                                                                               Show version information
78```
79 
80## OpenAPI support
81 
82- Currently, OpenAPI 2.0 and 3.0 are supported. 
83  - 3.1 is not (at least not until [microsoft/OpenAPI.NET](https://github.com/microsoft/OpenAPI.NET) supports it)
84- Specifications can be JSON/YAML and local (file) or remote (URL)
85- Only local $refs are supported
86 
87### OpenAPI custom extensions
88 
89A set of custom extensions is available to customize how your API should be exposed:
90- `info.x-mcp-instructions` (string): Textual instructions exposed by the MCP server during the initialize handshake
91- `operation.x-mcp-tool-name` (string): Custom tool name
92- `operation.x-mcp-tool-description` (string): Custom tool description
93- `operation.x-mcp-tool-enabled` (boolean): Enabled/disabled a specific operation (enabled by default)
94 
95## MCP features
96 
97Only STDIO transport is currently supported.
98 
99### Tools
100Operations ("endpoints") from your OpenAPI specification are translated to MCP [tools](https://modelcontextprotocol.io/docs/concepts/tools)
101- All path/query/JSON body parameters are exposed (using their JSON schema)
102- Response is returned as-is
103- By default, the tool name is computed using first the `operation.x-mcp-tool-name` extension, then the [operation.operationId](https://swagger.io/docs/specification/v3_0/paths-and-operations/#operationid) and then `{httpMethod}_{escaped_path}`
104  - The tool naming strategy can be defined via the `--tool-naming-strategy` option.
105  - ⚠️Tools are discarded if their name don't match `^[a-zA-Z0-9_-]{1,64}$`
106- Tools description are extracted as follows: `operation.x-mcp-tool-description` ?? `operation.description` ?? `path.description`
107 
108### Tool call and host
109 
110When a tool is called, the MCP server will call the underlying endpoint. To determine which host to call a combination of parameters are used:
111- the `--host-override` option
112- your specification first [server](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/)'s URL if it's an absolute URL
113- the host of the remote OpenAPI provided
114- otherwise, an error is thrown
115 
116For example running `openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json`:
117- https://petstore3.swagger.io/api/v3/openapi.json defines a server, but its URL is relative (/api/v3)
118- so the host of the specification's own URL is used: https://petstore3.swagger.io and the relative path of the server is appended to it
119 
120## Authorization
121 
122### Bearer token
123 
124A token can be provided as option `--bearer-token`. It'll be provided to all calls as the `Authorization: Bearer {token}` header.
125It'll also be provided when fetching a remote specification.
126 
127### OAuth2
128 
129ClientCredentials, RefreshToken, Password are supported.
130If your OpenAPI specification declare [securitySchemes](https://swagger.io/docs/specification/v3_0/authentication/oauth2/) for those flows, the corresponding `tokenUrl` will be used.
131 
132## How to publish
133 
134Create a new tag/release 🤷