openapi-swagger-mcp

# openapi-swagger-mcp

A local MCP server that lets an AI agent read Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 specs, find operations, inspect their contracts and send real requests to the dev/UAT services you configure.

You describe your APIs and how to authenticate in one YAML or JSON file. The agent works through **ten fixed tools**, so the tool count does not grow with the number of endpoints.

## Before you start

You need:

- **Node.js 22.19 or newer** and npm.
- An API you can reach, and its Swagger/OpenAPI spec (a URL or a file).
- An MCP client that can launch a local stdio server.

> **Use this only against dev/UAT services.** The tools send real POST, PUT, PATCH and DELETE requests. There is no rollback and no server-side write gate. A confirmation prompt in your MCP client is the client's feature, not something this server enforces.
>
> **Think about where your data goes.** Tool arguments and results can be stored in your AI provider's conversation history. Responses are not scrubbed of tokens or personal data. Read secrets from environment variables or files instead of pasting them into the conversation.

## Quick start

### 1. Create a config file

Save this as `config.dev.yaml`:

```yaml
services:
  orders:
    baseUrl: http://localhost:8080/api/v1
    spec: http://localhost:8080/v3/api-docs
```

- `orders` is the service name the agent uses in tool calls.
- `baseUrl` is where requests are really sent, **including any prefix** such as `/api/v1`.
- `spec` is the Swagger/OpenAPI URL, or a file path such as `./openapi.json`.
- With no `auth` block, requests are anonymous.

The URLs above are examples. They only work if your own API is running there, so replace them with your dev/UAT addresses.

### 2. Check the config

```bash
npx -y @nhan7777/openapi-swagger-mcp@0.1.1 --config /absolute/path/config.dev.yaml --check
```

`ok: true` means the static checks passed. It does **not** mean the remote spec was fetched or any endpoint was verified: `--check` makes no network calls, does not log in, and does not create the artifact directory. See [Troubleshooting](#troubleshooting) for the report format and exit codes.

### 3. Add the server to your MCP client

For clients that use an `mcpServers` configuration, add this to the **client's MCP config file** (not to the YAML file above):

```json
{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@nhan7777/openapi-swagger-mcp@0.1.1",
        "--config",
        "/absolute/path/config.dev.yaml"
      ]
    }
  }
}
```

The file name and location depend on your client. If your client has a form for command, arguments and environment variables, enter the same values there. Not every client uses the `mcpServers` format, so adapt the snippet if yours differs. Use absolute paths so the server does not depend on the directory the client starts in.

This server uses **stdio**: the client starts the process and talks to it over stdin/stdout. There is no web UI and no HTTP port. stdout is reserved for MCP traffic and logs go to stderr. Do not add `--check` to the client entry, because that mode exits after checking.

### 4. Try it

Once the client is connected, ask:

> List the configured APIs. Find the operation that returns order details in the orders service, read its contract, and propose a request. Do not send anything until I give you an order ID.

## Configure your APIs

A fuller example with two services:

```yaml
# yaml-language-server: $schema=/absolute/path/to/config.schema.json
version: 1                 # optional
services:
  orders:
    baseUrl: https://orders.dev.example.test/api/v1
    spec: https://orders.dev.example.test/v3/api-docs
    auth:
      bearer: { token: { fromEnv: ORDERS_TOKEN } }

  catalog:
    baseUrl: http://localhost:8081
    spec: ./specs/catalog.yaml
```

YAML (`.yaml`, `.yml`) and JSON are both supported. For JSON, add `"$schema": "/absolute/path/to/config.schema.json"` so your editor can suggest keys. See the [complete example config](examples/config.example.yaml) and the [JSON Schema](config.schema.json).

Key rules:

- Relative paths in the config resolve from the **directory that contains the config file**, not from where you run the command.
- **The URL comes from `baseUrl`.** The operation `GET /orders/{id}` with `baseUrl: https://host/api/v1` calls `https://host/api/v1/orders/{id}`. The server ignores `servers`, `host` and `basePath` in the spec. `baseUrl` must not contain a username, password, query or fragment.
- **One environment per process.** For dev and UAT, create two config files and two MCP entries (for example `api-dev` and `api-uat`). Each process has its own credentials, cookies and artifacts. There is no `--env` flag and no tool for switching environments.
- A config change needs a restart of the MCP process. `refresh_specs` only reloads specs.

### Pass a token from the environment

```yaml
services:
  orders:
    baseUrl: https://orders.dev.example.test/api/v1
    spec: https://orders.dev.example.test/v3/api-docs
    auth:
      bearer: { token: { fromEnv: ORDERS_TOKEN } }
```

The server reads `ORDERS_TOKEN` from **its own process environment**. That is not the same as the environment of the shell where you tested the command: set it in the `env` field of the client entry, or wherever your client launches the process.

```json
{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": ["-y", "@nhan7777/openapi-swagger-mcp@0.1.1", "--config", "/absolute/path/config.dev.yaml"],
      "env": { "ORDERS_TOKEN": "replace-with-your-dev-token" }
    }
  }
}
```

The server does not load `.env` files. Changing the environment of another process does not change the environment of a running MCP server; restart it with the new values.

### Other ways to install

The `npx` commands above download the pinned version on first use. Alternatives:

```bash
# Global install; the command is then `openapi-swagger-mcp`
npm install -g @nhan7777/openapi-swagger-mcp@0.1.1

# From a source checkout (see Development)
npm ci && npm run build
node /absolute/path/to/openapi-swagger-mcp/dist/cli.js --config /absolute/path/config.dev.yaml
```

Do not install the unscoped npm package `openapi-swagger-mcp`. It belongs to someone else and is a different project. This package is `@nhan7777/openapi-swagger-mcp`.

## Discover and call an operation

### The normal flow

| Step | Tool | Example arguments |
|---|---|---|
| See services and revisions | `list_apis` | `{}` |
| Find an operation | `search_operations` | `{"service":"orders","query":"order detail","limit":5}` |
| Read its contract | `get_operation_schema` | `{"service":"orders","operation":"GET /orders/{id}","revision":"<revision-you-just-received>"}` |
| Send the request | `invoke_operation` | See below |

A complete `invoke_operation` call:

```json
{
  "service": "orders",
  "operation": "GET /orders/{id}",
  "revision": "<revision-you-just-received>",
  "input": {
    "path": { "id": "demo-123" },
    "query": { "includeItems": true },
    "headers": { "X-Request-ID": "demo-request" }
  }
}
```

`operation` is the key returned by search, usually `METHOD /path`. It is not the `operationId`. `revision` is the spec revision, which stops you calling an operation based on an outdated contract. When the spec changes, call `refresh_specs` with `{"service":"orders"}`, then search or read the contract again to get the new revision. A failed refresh keeps the last valid snapshot.

`search_operations` accepts `service`, `method`, `tag`, `includeDeprecated`, `limit` and `cursor`. Pass `nextCursor` with the same query to get the next page. Changing the query or the revision invalidates an old cursor.

### Request bodies

The snippets below are **fragments** that go inside `input`. They are not complete tool calls. A request has at most one body type.

Note the difference from auth recipes: `invoke_operation.input.body` uses the `json.value` and `form.fields` wrappers, while a recipe `body` uses plain `json` and `form` (see [Login and refresh](#login-and-refresh)).

JSON:

```json
{ "body": { "json": { "value": { "name": "demo", "quantity": 2 } } } }
```

Form (`application/x-www-form-urlencoded`):

```json
{ "body": { "form": { "fields": { "name": "demo", "tags": ["a", "b"] } } } }
```

You can set `contentType` inside `json` or `form` to pick one of the media types the operation declares.

For multipart and binary uploads, first allow directories in the config and create them:

```yaml
files:
  uploadRoots: [./fixtures]
  exportRoots: [./exports]
```

Then pass absolute paths in the tool call.

Multipart:

```json
{
  "body": {
    "multipart": {
      "fields": { "description": "demo" },
      "files": [
        { "field": "document", "path": "/absolute/path/fixtures/demo.pdf", "filename": "demo.pdf", "contentType": "application/pdf" }
      ]
    }
  }
}
```

Binary:

```json
{ "body": { "binary": { "file": "/absolute/path/fixtures/demo.bin", "contentType": "application/octet-stream" } } }
```

The multipart `files` array may repeat the same `field`. Files outside `uploadRoots`, symlinks that escape a root, and protected files are refused. The media type must match what the operation declares, so read the contract before sending.

### Choosing auth, and negative testing

`invoke_operation.auth` has four modes:

| Mode | Behavior |
|---|---|
| `{"mode":"default"}` or no `auth` | Use the service's default auth, or anonymous if it has none |
| `{"mode":"profile","profileId":"qa"}` | Use a named profile the service allows |
| `{"mode":"session","sessionId":"<id>"}` | Use an interactive session bound to the same service |
| `{"mode":"anonymous"}` | Inherit no credentials or cookies. Data you pass explicitly in `input` is still sent |

To test a wrong token, pass your own `input.headers.Authorization`. It overrides the matching credential for that request only, leaves managed credentials untouched, and does not trigger an automatic ref