OpenAPI Swagger MCP

openapi-swagger-mcp

A local MCP server that connects your AI assistant to the dev/UAT APIs you configure. Ask it to find an endpoint, explain its inputs, send a request and inspect the response using your Swagger 2.0 or OpenAPI 3.0/3.1 spec.

For example: “Find the order details endpoint and explain the required parameters before calling it.”

You configure the API addresses and authentication in a YAML or JSON file. Your MCP client starts the server, and your assistant uses its ten fixed tools regardless of how many endpoints you have.

New here? Follow Quick start, then try Everyday usage. You do not need to write tool calls yourself.

Already connected? Jump to Choose your next step, Troubleshooting or Tool reference.

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:

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.

Before continuing: replace both URLs and save the file. Note its absolute path; you will use that same path in the next two steps.

2. Check the config

npx -y @nhan7777/openapi-swagger-mcp@0.1.2 --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 for the report format and exit codes.

Expected result: the command exits with code 0 and the report contains "ok": true. If it does not, fix the reported field before connecting your client.

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):

{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@nhan7777/openapi-swagger-mcp@0.1.2",
        "--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. Connect and check API availability

Save the client configuration and restart or reconnect the MCP server in your client. Ask:

List the configured APIs and report whether the orders spec loaded. If it failed, explain the error without making any business API requests.

Expected result: the assistant finds orders, its spec revision and its operation count. Unlike --check, this step loads the spec. If the service is unavailable, follow Troubleshooting.

5. Inspect your first endpoint

Ask:

Find the operation that returns order details in the orders service. Read its contract and explain the required inputs. Do not send the request yet.

Expected result: an operation such as GET /orders/{id} and the inputs declared by your own spec. The example path is not guaranteed to exist in your API.

You are now ready to use the server. If the endpoint requires a token, configure authentication before calling it.

Choose your next step

Read only the section that matches your task:

Everyday usage

Use normal language in your MCP client. Replace service names, IDs and paths in these prompts with your own. The assistant handles tool arguments; inspect Request and response reference when you need exact syntax.

Find an endpoint without sending a request

In orders, find the endpoint for order details. Read its contract and explain required parameters, authentication and expected responses. Do not call it.

Send a request and understand the result

After checking the operation and providing a real test ID:

Call the order details GET operation in orders for ID demo-123. Report the HTTP status, relevant response fields and any contract diagnostics. Do not retry automatically.

An HTTP response and a contract diagnostic answer different questions: the status tells you what the API returned; diagnostics tell you how the request or response compares with the spec. A successful status does not prove the response matches the contract.

Prepare a write before authorizing it

Find the create-order operation in orders. Read its contract and propose a request using the test data I provide. Show the target service and payload, then wait for my confirmation before sending.

This is an instruction to your assistant, not a server-enforced approval gate. POST, PUT, PATCH and DELETE requests can change real data.

Choose a service or account explicitly

Use orders-uat for this task. Inspect its order details contract first. Do not call orders-dev.

If you configured multiple profiles:

Use the qa profile allowed by orders. Check its auth status without showing credentials, then explain whether it is ready for a request.

Inspect more of a response

Read the returned artifact at /data/items. If it is paginated, continue using nextOffset. Report whether the response body is complete.

For files, configure export roots first and give the assistant a new destination path. Export never overwrites an existing file.

Configure your APIs

A fuller example with two services:

# 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. The configuration cookbook starts with an anonymous service and offers opt-in examples by scenario. Copy only the blocks you need; the JSON Schema is the field reference.

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.
• Environments are just services. The server has no environment concept, no --env flag and no switching tool. Give each environment's service a unique id (for example orders-dev and orders-uat) and tell the agent which one to use. Services that share one identity provider can share a profile, so they share one token pair and one refresh. If environments must stay isolated, use separate config files and MCP entries; each process then has its own credentials, cookies and artifacts.
• A config change needs a restart of the MCP process. refresh_specs only reloads specs.

Pass a token from the environment

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.

{
  "mcpServers": {
    "api-dev": {
      "command": "npx",
      "args": ["-y", "@nhan7777/openapi-swagger-mcp@0.1.2", "--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:

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

# 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.

Authentication

Pick the approach that matches your API:

Start with the simplest option your API supports. A ready token needs only static auth; recipes and sessions are optional. The YAML examples in this section are configuration blocks to merge at the stated location, not commands to run. Tool examples are JSON arguments for the assistant, not shell commands.

For authenticate and get_auth_status, provide exactly one target: {"service":"orders"} or {"profile":"qa"}, never both. authenticate also accepts "action":"refresh"; omitting action selects authentication (or reloading static sources when there is no login recipe).

Static credentials

Place one of these auth blocks inside a service, alongside baseUrl and spec (for example under services.orders). For a shared identity, put it inside a named profile instead.

Bearer token

auth:
  bearer:
    token: { fromEnv: ORDERS_TOKEN }

The server adds Authorization: Bearer <token>. The source value holds only the token, without the Bearer prefix.

Basic authentication

auth:
  basic:
    username: tester
    password: { fromEnv: API_PASSWORD }

Username and password are read independently and Basic-encoded. Both can also come from a file or fromCredential. Only a Basic literal may be an empty string.

API key in a header, query string or cookie

auth:
  apiKey:
    header: X-API-Key
    value: { fromEnv: API_KEY }

Replace header with query or cookie if your API needs that. Each entry picks one destination. You can also use a list and combine methods:

auth:
  bearer: { token: { fromEnv: ACCESS_TOKEN } }
  apiKey:
    - { header: X-CSRF-Token, value: { fromEnv: CSRF_TOKEN } }
    - { query: tenant, value: demo }
  cookies: true

Bearer, API key and the cookie jar can be combined. Bearer and basic cannot, because both use Authorization. Header names that collide case-insensitively are rejected. Query and cookie names are case-sensitive.

Cookie jar

auth: { cookies: true } enables the auth's own cookie jar. It is not a raw Cookie string. It is normally paired with a login recipe that has capture.cookies: true (see below). A cookie-only auth is not considered logged in while the jar is empty. To import cookies you already have, use a session.

Secret sources

The same syntax works for token, value, username, password and the initial values in credentials:

fromCredential cannot be used in initial credentials, in catalog credentialSources, or in spec-fetch auth. Env and file values for a binding must be strings; objects and numbers are not silently converted. A missing source never silently falls back to anonymous. Secret files are protected from upload and export, but you are responsible for their permissions, and you should not commit them.

Multiple accounts and shared profiles

profiles:
  qa:
    auth: { bearer: { token: { fromEnv: QA_TOKEN } } }
  admin:
    auth: { bearer: { token: { fromEnv: ADMIN_TOKEN } } }

services:
  orders:
    baseUrl: https://orders.dev.example.test
    spec: ./orders.json
    auth:
      profiles: [qa, admin]
      defaultProfile: qa
  reports:
    baseUrl: https://reports.dev.example.test
    spec: ./reports.json
    auth: { profile: qa }

• A call to orders with no auth choice uses qa. To use admin, pass "auth":{"mode":"profile","profileId":"admin"} to invoke_operation.
• If a service lists profiles but has no defaultProfile, requests are anonymous by default. The first profile is never picked for you. Auth tools aimed at that service ask you to name a profile.
• To control a profile directly, call authenticate or get_auth_status with {"profile":"qa"}. Do not pass both service and profile.
• A profile is usable only on services that reference it. Two services using qa share the same credentials, cookie jar and refresh task. Cookies are still scoped by domain and path.
• A named profile can have its own credentials, authentication and refresh. For recipes, set request.service explicitly; it may point to a separate identity service. That only lets the recipe call that operation. It does not give the identity service your business credentials.
• A service that references a profile must not also have its own credentials, authentication or refresh. Put them in the profile.

Login and refresh

Use a recipe when you must call an API to obtain credentials. A username and password are not required: the body can be a grant code, client credentials, or whatever your API's contract needs.

Three parts have different roles:

• auth: what to send on business requests.
• credentials: initial named values. They are not sent unless referenced.
• authentication / refresh: call one operation, then capture the result.

Example: grant code plus refresh token

services:
  accounts:
    baseUrl: https://accounts.dev.example.test
    spec: https://accounts.dev.example.test/v3/api-docs
    auth:
      bearer: { token: { fromCredential: accessToken } }
      apiKey: { header: X-CSRF-Token, value: { fromCredential: csrf } }
      cookies: true
    credentials:
      grantCode: { fromEnv: GRANT_CODE }
    authentication:
      request:
        operation: POST /session/exchange
        body:
          json:
            grantCode: { fromCredential: grantCode }
      capture:
        credentials:
          accessToken: { bodyPointer: /session/accessToken }
          refreshToken: { bodyPointer: /session/refreshToken }
          csrf: { header: X-CSRF-Token }
        cookies: true
    refresh:
      request:
        operation: POST /session/refresh
        body:
          form:
            refresh_token: { fromCredential: refreshToken }
      capture:
        credentials:
          accessToken: { bodyPointer: /access_token }
          refreshToken: { bodyPointer: /refresh_token }

Both operations must exist in the spec. A JSON Pointer such as /session/accessToken reads response.session.accessToken. The refresh token stays in the credential store. In this example it is sent only by the refresh recipe, never on business requests.

How to use it. The tool name comes first, followed by its JSON arguments. These are not shell commands.

1. authenticate with {"service":"accounts"}.
2. get_auth_status with {"service":"accounts"} until it stops reporting recovering.
3. When the state is ready, call the API normally.
4. To refresh manually: authenticate with {"service":"accounts","action":"refresh"}.

You can also ask the agent: "Authenticate the accounts service with the configured recipe, wait until it finishes, then report the status. Do not show any credentials."

Rules to remember

• authenticate runs only authentication. Without a recipe it reloads static sources. It never logs in automatically when a business call lacks credentials.
• action: refresh runs only refresh. Without a refresh recipe it fails locally with AUTH_REFRESH_UNAVAILABLE.
• A 401 can start a background refresh, but the original request is never replayed automatically. The caller still receives the 401 plus authRecovery. After the refresh finishes, you or the agent decide whether to call again.
• A 403, an anonymous request, a session, or a request with an Authorization override does not trigger a refresh.
• While a recipe runs, new business requests fail with AUTH_RECOVERING. Calling the same action again joins the running one; a different action fails with AUTH_BUSY.
• A failed refresh does not retry in a loop. Request a retry explicitly with authenticate and the right action.
• Captured credentials, cookies and binding updates are applied together. If a required capture is missing, nothing is applied partially. A credential not named in the capture keeps its old value, so to rotate a refresh token you must capture it again.
• Header captures in managed recipes keep the header content as-is, including Bearer. A scalar capture accepts a non-empty string or a finite number; numbers become strings.
• A recipe accepts HTTP 200-299 by default. Set successStatuses: [200, 201] to change that. Recipes do not follow redirects, do not replay, and do not run prerequisite recipes.

Recipe requests. request supports service, operation, path, query, headers, cookies, body and auth.

• service defaults to the service that owns the recipe. A recipe in a named profile must set it explicitly.
• request.auth defaults to anonymous and does not inherit the owner's bearer or cookies. To send them, declare the auth methods explicitly. cookies: true uses the current jar.
• Templates are substituted in payloads: {fromEnv}, {fromFile,pointer?}, {fromCredential}. Wrap a value as {literal: {fromEnv: "text"}} to send that object unchanged.
• A fromCredential name must be declared in initial credentials or in a capture. Authentication can only use credentials with an initial definition, not its own future captures. Refresh can use what authentication captured.
• A capture needs non-empty credentials or cookies: true. Capturing cookies requires the owner to have auth.cookies: true.
• An authentication capture starts a fresh cookie jar. A refresh keeps and updates the existing jar.

A recipe body takes one of these forms. They are alternatives, so do not paste all four into one recipe:

# JSON; you can add contentType next to json
body: { json: { name: demo } }

# application/x-www-form-urlencoded, for example client credentials
body:
  form:
    grant_type: client_credentials
    client_id: { fromEnv: CLIENT_ID }
    client_secret: { fromEnv: CLIENT_SECRET }

# Multipart; files must be under uploadRoots
body:
  multipart:
    fields: { note: demo }
    files: [{ field: document, path: ./fixtures/demo.pdf }]

# Binary
body: { binary: { file: ./fixtures/demo.bin, contentType: application/octet-stream } }

File paths in recipes are fixed configuration. They cannot come from credential substitution.

OTP, SSO and interactive sessions

Use a session when an agent and a person must work through several steps: request an OTP, enter it, receive a token or cookie, then call the API. The server never requests an OTP, polls, opens a browser or solves a CAPTCHA by itself. A session is bound to one service.

Capture from a response

1. Call the operation that requests the OTP once, on explicit request, with auth: {mode: anonymous}.
2. The person provides the OTP. Call the verify operation with invoke_operation:

{
  "service": "accounts",
  "operation": "POST /otp/verify",
  "revision": "<revision>",
  "auth": { "mode": "anonymous" },
  "input": { "body": { "json": { "value": { "code": "<OTP-provided-by-the-user>" } } } },
  "capture": {
    "tokens": [
      { "id": "access", "type": "bearer", "from": "body", "pointer": "/token" }
    ],
    "cookies": true
  }
}

1. Read capture.sessionId when capture.state is captured.
2. Call business operations with auth: {mode: session, sessionId: ...}.

Enable capture.cookies only if the response really sets cookies. To capture a token from a header, use {"id":"access","type":"bearer","from":"header","header":"Authorization"}. Unlike managed recipes, a session's bearer-header capture strips the Bearer prefix. For an API key, use type: apiKey with in: header|query|cookie and name.

A capture applies only to 200-299 responses by default; set successStatuses to change that. A failed capture never updates a session partially. To update an existing session, add capture.sessionId.

Import credentials you already have

Prefer declaring a catalog in the config:

credentialSources:
  qaToken: { fromEnv: QA_SESSION_TOKEN }

Then call manage_session:

{
  "action": "create",
  "service": "accounts",
  "credentialSourceIds": [{ "sourceId": "qaToken", "type": "bearer" }]
}

Only ids declared in top-level credentialSources can be imported. Inline secrets in a service or profile, and captured refresh tokens, do not appear in the catalog automatically.

If you must import values directly (they may end up in AI conversation history):

{
  "action": "create",
  "service": "accounts",
  "credentials": {
    "components": [{ "id": "access", "type": "bearer", "value": "<token>" }],
    "cookies": [{ "name": "sid", "value": "<cookie-value>" }]
  }
}

Inspect with {"action":"inspect","sessionId":"<id>"}, or omit sessionId to list sessions. Delete with {"action":"delete","sessionId":"<id>"}. Inspect returns metadata only, never secrets.

Sessions are bound to one service, do not refresh themselves, do not change managed profiles, and are never promoted to profiles. They live in memory and disappear when the process ends.

Large responses and files

The server stores responses as artifacts and returns a bounded view, so long files and base64 strings do not flood the conversation.

• bodyTransformed: true: the view was shortened and is not the full response.
• omissions: which fields were shortened, why, their JSON Pointer and the artifact id.
• rawBodyArtifact: the response entity bytes after HTTP content decoding, with metadata and a SHA-256.

Read part of an artifact

Call read_artifact with a pointer:

{ "artifactId": "<id>", "pointer": "/data/status" }

Or page through it:

{ "artifactId": "<id>", "offset": 0, "limit": 4096 }

Use nextOffset from the result to continue. A pointer to a string returns text, and a pointer to an object or array returns JSON. Reading a binary artifact returns metadata only; use export to get the file. Pointers work on the parsed JSON value (number precision is limited); exporting original keeps the exact bytes.

Export a file

The destination must be under files.exportRoots. Call export_artifact:

{
  "artifactId": "<id>",
  "pointer": "/data/imageBase64",
  "destination": "/absolute/path/exports/image.png",
  "representation": "decoded"
}

Export never overwrites an existing file and never follows a symlink out of a root. File names from Content-Disposition are not trusted. Artifacts exist only for the lifetime of the process and are removed on normal shutdown; exported files stay.

To mark a base64 field explicitly in the config:

encodedFields:
  - service: orders
    pointer: /data/*/thumbnail
    encoding: base64
    mediaType: image/png

* matches one path segment. Add operation to limit a rule to one operation. Schema hints such as format: byte, contentEncoding and data URIs also help confirm an encoding. A string that merely looks like base64 is not asserted to be base64.

If a response exceeds responseBytes, you still get the status and headers, but the body may be incomplete (bodyComplete: false). Total artifact storage is capped by sessionArtifactBytes.

Troubleshooting

Start with the config check:

npx -y @nhan7777/openapi-swagger-mcp@0.1.2 --config /absolute/path/config.yaml --check

The report contains ok, services, checks, remoteSpecsChecked: false and operationsChecked: false. Each check has a field, a state (ok, pending or error) and possibly a code.

• pending means a credential will be captured at runtime. It is not a static error.
• It checks env and file sources (even when a recipe exists), local spec and CA files, and upload/export roots.
• It does not fetch remote specs, parse spec content, check operations remotely, run recipes or create the artifact directory.
• If the config cannot be parsed or fails the schema, stderr has a sanitized error and stdout is empty. If it parses, stdout has one JSON report with no secret values.

Common problems

Restart or refresh? Config changes need a restart of the MCP process. refresh_specs only reloads specs. authenticate without a recipe reloads static auth sources, not the whole config.

Request and response reference

The normal flow

A complete invoke_operation call:

{
  "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).

JSON:

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

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

{ "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:

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

Then pass absolute paths in the tool call.

Multipart:

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

Binary:

{ "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:

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 refresh.

The server serializes what you give it and does not fix your data. It adds no defaults, does no type coercion, and does not strip unknown fields or null. Omitting the body is different from sending {"json":{"value":null}}, which sends the bytes null. HTTP 4xx/5xx responses are real results and are not turned into "tool failed validation" errors.

Requests that cannot be sent safely are blocked locally: a missing path parameter, a path escape, CR/LF in a header, a media type the operation does not declare, or an attempt to override headers the transport manages.

Reading the result

• sent: false: the request was not sent. Look at error.code and error.message.
• http.status and http.headers: the actual HTTP outcome.
• bodyView: the part of the response meant for the agent to read.
• diagnostics.request and diagnostics.response: spec-based checks, for diagnosis only. They do not replace the HTTP outcome. States are valid, invalid, not_available and error.
• bodyComplete: false: the body is partial because of a limit or a stream error. Do not conclude the whole response was valid.
• authRecovery: the state of a background refresh after a 401. It does not mean the request was replayed.
• Network, TLS and timeout failures do not produce a fake HTTP status. error.mayHaveBeenSent says whether the request may already have left the machine. Be careful about retrying write operations.

Redirects are not followed by default. With followRedirects: true, only same-origin redirects are followed, within a limit: 303, and POST after 301/302, become GET; 307/308 keep the method and body. Credentials are never forwarded to another origin.

Advanced configuration and limitations

Authentication for spec downloads and $refs

Spec-fetch auth is separate from business auth. It only uses static secrets and never runs a recipe:

services:
  privateApi:
    baseUrl: https://api.dev.example.test
    spec:
      source: { url: https://docs.dev.example.test/openapi.json }
      auth:
        bearer: { token: { fromEnv: DOCS_TOKEN } }
      allowedOrigins: [https://schemas.dev.example.test]
      roots: [./specs]
    auth:
      bearer: { token: { fromEnv: API_TOKEN } }

Spec-fetch credentials are sent only to the origin of the spec source, never to a different origin reached through a $ref. A remote spec cannot reference local files. A local $ref must stay inside the allowed roots; the directory of a local spec is used as that spec's root. Spec fetches do not follow redirects. A missing or broken ref causes that service's snapshot to be rejected, and other services keep working.

Imperfect specs: warnings instead of errors

Framework-generated specs (NestJS, for example) often have small mistakes. These three do not block a service. They appear in warnings from list_apis. The list is capped at 20 entries, 4096 bytes in total, and 512 bytes and one line per entry. Priority order is excluded operations, then security schemes, then duplicate operationId. Exact counts are in warningSummary (total, shown, omitted, excludedOperations), not in an extra line at the end of the list. If list_apis exceeds its output budget, warning text is shortened (counts stay accurate). If even the metadata is too large, the result has servicesInline: false and a servicesArtifact you read in full with read_artifact.

Other problems still block the whole service with SPEC_INVALID: for example a path template {id} with no matching parameter, a missing $ref target, or a malformed OpenAPI structure.

Warnings only report problems. They do not repair the spec, so fix it at the backend where possible.

$ref combined with a method or parameters is rejected. Any object in a spec that has a string $ref together with get, put, post, delete, options, head, patch, trace or parameters is refused (<document>: an object combines $ref with execution siblings (a method or parameters)). Tools disagree about what to do here (ignore, override or merge), and bundlers merge silently, so the server does not pick one; the spec author must choose. summary, description and x-* siblings are still allowed.

The scan runs on every original document (the root and every allowed file or URL a $ref points to) as it is read, before the bundler merges them, and again on the bundled document. This is because an extended $ref on a container (for example paths: { $ref: 'p.json', '/a': { $ref: '#/x' } }) can make the bundler produce a $ref with a method from two objects that were each valid on their own. The server checks object shape before and after bundling and does not re-resolve $ref paths itself. The cost: every object with this shape is rejected, including not only sample data (example, enum, default, x-*) but also schemas, Links and Responses, including shapes that only appear after a merge. This is a compatibility limit. When you hit it, change the spec (rename the key, or remove the $ref from that object) if doing so does not change what the spec means.

Extended $ref is accepted. When a $ref is extended on a container and the merged result no longer contains a forbidden combination, the server accepts the bundler library's merge: the extender wins for scalar values, objects are merged, and arrays are replaced entirely. For example, if an external file declares parameters with a required query parameter external, and the extender declares parameters with root, the published contract has only root. The external parameter disappears because arrays are replaced, not combined. The contract published over MCP, and used to serialize requests, is the one after bundling and validation. There is no evidence that the real server accepts this contract, so read it with get_operation_schema and try it in a suitable environment before sending requests with side effects.

Read limits. The number of distinct $ref strings the bundler asks to read is capped by refGraphDocuments. The total bytes read, including the same file read several times under different spellings such as .//a.json, is capped by refGraphBytes. Exceeding a configured read budget stops with SPEC_LIMIT_EXCEEDED. These input byte budgets are not hard limits on heap or RSS. Spec load and parse errors are capped at 2048 bytes.

TLS per service

tls:
  caFile: ./certs/dev-ca.pem
  verify: true

This block goes under a service. verify: false turns off TLS verification for that service only and produces a warning. Use it only when you really need it in a test environment; it is not the way to fix a default certificate problem. No tool changes TLS settings at call time.

Files and limits

files:
  uploadRoots: [./fixtures]
  exportRoots: [./exports]
  artifactRoot: ./runtime-artifacts
limits:
  requestTimeoutMs: 30000
  responseBytes: 52428800
  uploadBytes: 52428800
  toolOutputBytes: 32768

Declare only the values you want to change. Every limit is a positive integer with a maximum; check the JSON Schema for the ranges.

uploadRoots and exportRoots default to empty, so upload and export are disabled until you declare them. artifactRoot may not exist yet; the server creates it at runtime.

Limitations

• A local MCP server over stdio. It is not a hosted gateway or an HTTP MCP server.
• Not a workflow engine: one recipe is one operation. The agent or a person orchestrates multi-step flows.
• No automation of OAuth/PKCE callbacks, OTP polling, CAPTCHA or browser login. No scripting, HMAC signing or mTLS client authentication.
• No telemetry. Specs and responses are untrusted data, not instructions for the agent, and descriptions and extensions are never executed.
• Validation depends on spec quality. An unknown format is recorded as unverified, not as passed. Search is deterministic token scoring; the project makes no claims about token savings or semantic search accuracy.
• Compatibility note: older config and tool forms were removed with no aliases. bearer.login, profile components/recovery, service-level allowedProfiles/defaultProfile, $source/$component, authenticate_profile and get_profile_status no longer work. Use the forms in this guide.

Tool reference

The tool count does not grow with the number of endpoints. No tool accepts an arbitrary URL to call outside the configured services, an arbitrary env or file secret name, a script, or a parameter that switches environments.

Development

Work from a source checkout:

npm ci
npm run build
npm run typecheck
npm run gen:schema
npm test
npm run test:integration
npm run smoke
npm run verify:package
npm audit --omit=dev --audit-level=high

Build before the integration tests and the smoke test, because some of them run the compiled CLI over stdio. Tests use a loopback backend, synthetic data and self-signed certificates meant only for tests. No real credentials are needed. Run npm run gen:notices to update the third-party notices when dependencies change.

npm test includes both unit and integration tests; npm run test:integration is an optional subset, not an additional gate. CI also validates the configuration cookbook with synthetic sources and rejects changes produced by gen:schema that were not committed. After changing the config schema, regenerate and include config.schema.json in your change.

Tag publication calls the same nine-cell CI matrix on the tag's commit and waits for every cell to pass. Only then does the publish job build and verify its own tarball, check its SHA-256 companion and publish those exact bytes through npm trusted publishing. The tag must match the package version and its commit must belong to main.

npm run verify:package needs npm run build first. It packs the package for real, installs the tarball into a separate consumer directory, runs --check, the bin shim and the smoke test against the installed copy, then audits that installed copy. Only if all of that passes does the tarball land in .release/<name>.tgz with a .sha256 file. If the audit fails, the tarball is kept as evidence in .release/diagnostic/NOT-RELEASABLE-.... npm pack --dry-run is not a substitute. Verifying a local candidate this way is separate from publishing it. Publishing is a separate, deliberate registry action. The CI matrix (Ubuntu, macOS and Windows with Node 22.19.0, 22 and 24) is its own release condition.

Released under the MIT license. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.