home / mcp / swagger navigator mcp server

Swagger Navigator MCP Server

Provides dynamic API discovery and intelligent search across Swagger/OpenAPI sources for fast API client generation.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aaydin-tr-swagger-navigator-mcp": {
      "url": "https://api.github.com",
      "headers": {
        "ACCEPT": "application/vnd.github.v3+json",
        "API_KEY": "prod-internal-api-key",
        "CONFIG_PATH": "./swagger-navigator-mcp.config.yaml",
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

You can use the Swagger Navigator MCP Server to automatically discover, index, and search Swagger/OpenAPI specifications from multiple sources. It provides intelligent endpoints for querying API schemas, helping you build clients and integrations faster by offering structured API information and fuzzy search across endpoints.

How to use

You will interact with the MCP server through a client or your development environment. Start by loading one or more API specifications, then ask for endpoint details, schema information, or a list of available endpoints. The server returns structured API data you can use to generate clients, anticorruption layers, or type definitions. Use natural language queries like “show me the /users GET endpoint” or “find endpoints related to authentication,” and the system will return relevant endpoint data ranked by relevance.

Typical usage patterns include:

How to install

Prerequisites: you need Node.js and npm installed on your machine. Ensure you have at least Node.js 14+ and npm available in your shell.

Install dependencies and build the project locally:

npm install
npm run build

Start the server using the provided configuration. You have two common options: - Run via the standard MCP CLI using a local config file with the environment variable pointing to the config path: - Start via an HTTP-based MCP source configuration by running the server with a prepared config that references remote OpenAPI sources. The following examples show the concrete commands you can run.

CONFIG_PATH=./swagger-navigator-mcp.config.yaml npm start
```

```
# Alternative development command if you prefer a dev workflow
npm run dev

Configuration examples and notes

Below are representative configuration snippets you can adapt for your environment. The first example demonstrates a local source and two remote HTTP sources with authentication headers. The second example shows how to run the MCP CLI via npx with environment-variable-based config loading.

# swagger-navigator-mcp.config.yaml
sources:
  - name: "petstore-local"
    source: "./specs/petstore.json"
    description: "Local Petstore API specification"

  - name: "github-api"
    source: "https://api.github.com"
    description: "GitHub REST API v3"
    headers:
      Authorization: "token ${GITHUB_TOKEN}"
      Accept: "application/vnd.github.v3+json"

  - name: "internal-api"
    source: "https://internal.company.com/api/swagger.json"
    description: "Internal company API"
    headers:
      X-API-Key: "${API_KEY}"

search:
  fuzzyThreshold: 0.6
refreshInterval: 300
```

```
# CLI stdio example (from usage with Cursor)
{
  "mcpServers": {
    "swagger_navigator": {
      "command": "npx",
      "args": ["-y", "swagger-navigator-mcp"],
      "env": {
        "CONFIG_PATH": "path/to/swagger-navigator-mcp.config.yaml"
      }
    }
  }
}

Available tools

list_all_sources

Retrieves a comprehensive list of all available Swagger/OpenAPI sources in the system. Provides overview of loaded APIs and returns source names for use with other tools.

list_endpoints_for_source

Retrieves all endpoints from a specific API source with pagination support. Returns endpoints with path, method, description, and metadata.

search_endpoint

Intelligently searches endpoints using fuzzy matching across multiple attributes and returns a ranked list of matching endpoints with relevance scores.