@rekl0w/mcp-openapi-discovery

@rekl0w/mcp-openapi-discovery is a TypeScript MCP server that can:

• detect OpenAPI / Swagger documents from a URL,

• inspect and summarize endpoints,

• trace field and identifier usage across the API,

• and execute real HTTP requests against those endpoints with auth and payload support.

It is designed for documentation-first API workflows where you want an MCP client to move from "find the spec" to "understand the endpoint" to "call the endpoint".

Published package:

• npm: @rekl0w/mcp-openapi-discovery

Why this project exists

Many APIs expose documentation pages, but not always the raw spec URL directly. This server helps bridge that gap by discovering the OpenAPI document behind a docs page and turning it into callable MCP tools.

It is especially useful for:

• Swagger UI deployments

• ReDoc documentation pages

• Laravel + L5 Swagger projects

• APIs exposing openapi.json, swagger.json, openapi.yaml, or swagger.yaml

• docs pages that reference the spec indirectly through HTML or JS config

Features

• Detect OpenAPI / Swagger specs from docs pages or direct spec URLs

• Summarize API metadata, servers, tags, and endpoint counts

• List endpoints with filtering by method, tag, or path fragment

• Inspect request / response details for a specific endpoint

• Trace where identifiers like userId, accountId, or teamId appear across parameters and schemas

• Find endpoints that are structurally related to another endpoint

• Execute endpoints with:

  • path params

  • query params

  • custom headers

  • JSON payloads

  • form-urlencoded payloads

  • basic multipart form data

• Apply authentication with:

  • Basic auth

  • Bearer tokens

  • API keys

  • OAuth 2.0 password flow

  • OAuth 2.0 client credentials flow

  • automatic auth selection based on the OpenAPI security scheme

Available MCP tools

Requirements

• Node.js 18+

• npm 9+ recommended

Installation

Install from npm:

npm i @rekl0w/mcp-openapi-discovery

Or install project dependencies when working from source:

npm install
npm run build

Running locally

Run the stdio MCP server after building:

node dist/index.js

For development:

npm run dev

Connecting from an MCP client

The easiest way to use the published package in MCP clients is to let the client auto-install and run it through npx.

Auto-install from npm with npx

If your MCP client supports a command + args stdio server definition, use:

{
  "command": "npx",
  "args": ["-y", "@rekl0w/mcp-openapi-discovery"]
}

This is usually the cleanest setup for clients such as VS Code and Cursor-like MCP clients because the package is downloaded automatically when the server starts.

VS Code (.vscode/mcp.json)

VS Code supports mcp.json and can run local MCP servers through npx.

{
  "servers": {
    "openapi-discovery": {
      "command": "npx",
      "args": ["-y", "@rekl0w/mcp-openapi-discovery"]
    }
  }
}

Cursor-style MCP config

For MCP clients that use a JSON config with mcpServers, a typical setup looks like this:

{
  "mcpServers": {
    "openapi-discovery": {
      "command": "npx",
      "args": ["-y", "@rekl0w/mcp-openapi-discovery"]
    }
  }
}

Local build instead of npm

If you prefer to run the local build directly instead of using npm, point your MCP client at dist/index.js.

Claude Desktop example (Windows)

Add this to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "openapi-discovery": {
      "command": "node",
      "args": ["C:/absolute/path/to/project/dist/index.js"]
    }
  }
}

Use an absolute path. On Windows, either forward slashes or escaped backslashes work.

Example use cases

• Detect the spec behind https://example.com/docs

• List endpoints from https://api.example.com/openapi.json

• Inspect the PUT /users/{id} endpoint

• Filter only POST endpoints tagged with users

• Trace where userId appears across the API

• Find endpoints related to GET /users/{id}

• Send a real POST /orders request with a JSON payload

• Log in with username/password, obtain a token, and call a protected endpoint

Structured tracing

Beyond plain endpoint listing, this server can help answer questions like:

• “Where is userId used?”

• “Which endpoints are related to GET /users/{id}?”

• “Is this identifier coming from a response body, a query parameter, or a path parameter?”

This is intentionally more structured than pure semantic search. Instead of only doing natural-language similarity, the server can inspect:

• path parameters

• query parameters

• request body fields

• response body fields

• shared resource names in paths

• shared identifier patterns such as userId, accountId, teamId, or entity-specific id fields

Example tracing queries

Use trace_parameter_usage when you want to follow a field such as userId across the API surface.

Use find_related_endpoints when you already know one endpoint and want to discover nearby or dependent endpoints, such as child resources or endpoints using the same identifiers.

Endpoint execution and authentication

The call_endpoint tool can execute actual API calls, not just describe them.

Supported auth strategies:

• basic

• bearer

• apiKey

• oauth2-password

• oauth2-client-credentials

• auto

In auto mode, the tool inspects the endpoint’s effective OpenAPI security requirements and tries to apply the most appropriate authentication strategy from the credentials you provide.

Supported request body styles

• JSON

• application/x-www-form-urlencoded

• simple multipart/form-data

• raw string bodies via rawBody

You can also override the outgoing content type explicitly with contentType.

Example call_endpoint inputs

JSON body + API key

{
  "url": "https://orders.example.com/openapi.json",
  "method": "POST",
  "path": "/orders",
  "body": {
    "productId": 42,
    "quantity": 3
  },
  "auth": {
    "apiKey": "your-api-key"
  }
}

OAuth password flow

{
  "url": "https://auth.example.com/openapi.json",
  "method": "GET",
  "path": "/me",
  "auth": {
    "username": "demo",
    "password": "super-secret",
    "clientId": "client",
    "clientSecret": "client-secret",
    "scopes": ["profile"]
  }
}

Path params + query params

{
  "url": "https://api.example.com/openapi.json",
  "method": "GET",
  "path": "/users/{id}",
  "pathParams": {
    "id": 123
  },
  "query": {
    "include": ["roles", "permissions"]
  }
}

Direct bearer token

{
  "url": "https://api.example.com/openapi.json",
  "method": "GET",
  "path": "/profile",
  "auth": {
    "strategy": "bearer",
    "token": "your-access-token"
  }
}

Validation

Run the full verification suite with:

npm run check

This runs:

• the TypeScript build

• the Vitest test suite

Development notes

• Runtime: Node.js 18+

• MCP SDK: @modelcontextprotocol/sdk v1

• Spec parsing: JSON / YAML + HTML discovery heuristics

• Request execution: real HTTP requests with automatic auth handling

• Test runner: vitest

Security notes

• Do not commit real credentials, client secrets, or access tokens.

• Prefer environment-specific client configuration over hardcoded secrets.

• Be careful when using this against production APIs.

• Review OpenAPI specs from untrusted sources carefully, especially when authentication and live request execution are involved.

Contributing

Issues and pull requests are welcome.

If you want to contribute:

1. fork the repository

2. create a feature branch

3. run npm run check

4. open a pull request with a clear description

Roadmap

• search_endpoints tool

• optional semantic-search layer on top of structured tracing

• broader Swagger UI / Scalar detection patterns

• external $ref resolution support

• richer Laravel-specific API summaries

• optional Streamable HTTP transport support

License

MIT