# OpenAPI to MCP

**Turn any OpenAPI/Swagger or REST API into an MCP server for Claude, ChatGPT and Copilot.** Powered by [AnythingMCP](https://github.com/HelpCode-ai/anythingmcp).

OpenAPI to MCP turns any REST API with an OpenAPI or Swagger spec into MCP tools that Claude, ChatGPT, Copilot and Cursor can call, without code. Import the spec and every operation becomes a tool with its parameters and auth. This repository runs the whole chain locally against a demo orders API.

**Last verified:** 2026-09-26 against the bundled demo orders API (OpenAPI 3.0.3, API-key auth) (docker compose up + scripts/smoke.mjs: spec import, tools/list, GET with query and path parameters, POST with a JSON body).  
**Adapter synced:** <!-- synced -->2026-09-26

Maintained by [helpcode.ai](https://helpcode.ai), the team that builds and maintains [AnythingMCP](https://github.com/HelpCode-ai/anythingmcp).

## Try it in five minutes

Needs Docker 24+, openssl and Node 18+.

```bash
git clone https://github.com/HelpCode-ai/openapi-to-mcp.git
cd openapi-to-mcp
./scripts/install.sh
npm install && node scripts/smoke.mjs
```

`install.sh` starts AnythingMCP and a small REST API ([`examples/api-demo`](examples/api-demo): customers and sales orders, protected by an API key), creates a REST connector with that key, imports `openapi.json` and creates an MCP API key. `smoke.mjs` lists the tools and asks for the open orders.

| OpenAPI operation | MCP tool | Changes data |
|---|---|---|
| `GET /customers` (`listCustomers`) | `listcustomers` | no |
| `GET /customers/{id}` (`getCustomer`) | `getcustomer` | no |
| `GET /orders` (`listOrders`) | `listorders` | no |
| `GET /orders/{orderNumber}` (`getOrder`) | `getorder` | no |
| `POST /orders/{orderNumber}/notes` (`addOrderNote`) | `addordernote` | yes |

Tool names are the `operationId` in lower case (or `<method>_<path>` without one); descriptions come from `summary` and `description`. The API key lives in the connector and never reaches the model.

## Use your own API

1. In the AnythingMCP UI, **Connectors → New connector → REST**: base URL and auth (API key, bearer, Basic, OAuth 2.0, HMAC…).
2. **Import → OpenAPI** with the spec URL, a Swagger UI page URL, or the spec pasted as JSON or YAML. OpenAPI 3.0, 3.1 and Swagger 2.0 work.
3. Rename tools with cryptic `operationId`s and rewrite descriptions in the words your users ask with.
4. Assign the connector to an MCP server whose role whitelists the operations the AI may call.

Through the API:

```bash
curl -s http://localhost:4000/api/connectors/$ID/import -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"source":"openapi","url":"https://api.example.com/openapi.json"}'
```

**Re-importing** updates changed operations, adds new ones and disables the ones that disappeared. Roles, response mappings and tools you disabled survive; names and descriptions are refreshed from the spec, so put wording you want to keep into the spec itself.

## Connect Claude, ChatGPT, Copilot or Cursor

- **Claude (claude.ai, Desktop, mobile):** *Customize → Connectors → Add custom connector*, paste your MCP server URL and sign in. Claude connects from Anthropic's cloud, so the URL must be public HTTPS: your AnythingMCP Cloud URL, or your own instance behind TLS.
- **Claude Code:**

  ```bash
  claude mcp add --transport http openapi-to-mcp http://localhost:4000/mcp --header "X-API-Key: <MCP_API_KEY>"
  ```
- **Cursor** (`.cursor/mcp.json`) and **VS Code / GitHub Copilot** (`.vscode/mcp.json`, key `servers` instead of `mcpServers`, plus `"type": "http"`):

  ```json
  { "mcpServers": { "openapi-to-mcp": { "url": "http://localhost:4000/mcp", "headers": { "X-API-Key": "<MCP_API_KEY>" } } } }
  ```
- **ChatGPT:** add the public HTTPS URL as a connector (app) in ChatGPT's settings. A `localhost` URL does not work there.

## Example prompts

- Which sales orders are still open, and when did we promise them?
- Show customer 2 and all of their orders.
- Which customers are in Switzerland?
- What is the total value of the open orders?
- Add a note to order SO-24044: "Customer asked for delivery before 10 am." (a write tool)
- Which tickets were opened today in our helpdesk API?

More in [examples/prompts.md](examples/prompts.md).

## Security

- **Credentials** stay in the connector, encrypted with AES-256-GCM; the model never sees them.
- **Roles** decide which operations each MCP server exposes. Start with the GET operations.
- **Response mapping** trims large or sensitive responses per tool before they reach the model.
- **Audit log:** every call with input, output, duration and status.

## FAQ

### How do I turn an OpenAPI spec into an MCP server?
Create a REST connector in AnythingMCP, import the spec (URL, Swagger UI page or pasted JSON/YAML), and add the MCP server URL to your AI client. Each operation becomes a tool; no code.

### Which spec versions work?
OpenAPI 3.0, OpenAPI 3.1 and Swagger 2.0.

### What if my API has no spec?
Import a Postman collection or cURL commands instead, or define the tools by hand in the visual editor.

### Where do the API credentials go?
Into the connector, encrypted with AES-256-GCM. They are added to each request by AnythingMCP; the model never sees them.

### Can I stop the AI from calling operations that change data?
Yes. Give the MCP server a role that whitelists only the GET operations; the others are invisible to that client.

### What happens when the API changes?
Re-import the spec. Changed operations are updated, new ones added, and removed ones disabled instead of failing at call time.

## Troubleshooting

| Problem | Fix |
|---|---|
| The import finds no operations | Point it at the JSON/YAML spec, or at the Swagger UI page: AnythingMCP looks for the spec behind it. |
| Tool names are unreadable | The spec has no `operationId`s. Add them to the spec, or rename the tools in the editor. |
| `401` from the API | The connector auth is missing or wrong. Check header name and key on the connector. |
| "SSRF" or "blocked host" error | The API is on a private network. Add its hostname to `SSRF_ALLOWED_HOSTS` on a self-hosted instance. |

## Related

- [soap-to-mcp](https://github.com/HelpCode-ai/soap-to-mcp): Turn any SOAP/WSDL web service into MCP tools for Claude & ChatGPT. Legacy SOAP APIs as AI tools, no code, self-hosted.
- [AnythingMCP](https://github.com/HelpCode-ai/anythingmcp): the open-source MCP server and gateway this repository is built on.

## License

AGPL-3.0-only. The adapter definition in `adapter/` comes from AnythingMCP (AGPL-3.0).