API Docs MCP Server

A Model Context Protocol (MCP) server that provides tools to explore and query API definitions from OpenAPI/Swagger JSON files.

Overview

This MCP server reads API definition files from the directory D:\My works\DauTuCong\Frontend\src\assets\api-definitions and provides various tools to search, explore, and retrieve information about the APIs defined in those files.

Related MCP server: mcp-swagger-schema

Features

• List all APIs: Get an overview of all available API definitions

• Search by tag: Find endpoints grouped by functional tags

• Search by path: Find endpoints using path pattern matching (supports regex)

• Get endpoint details: Retrieve complete information about specific endpoints including parameters, request bodies, and responses

• Get schema details: Explore data models and schemas defined in the API specifications

• List schemas: View all available schemas in a specific API definition

Installation

1. Install dependencies:

npm install

MCP Setup for AI Agents

This MCP server can be used with various AI coding assistants and agents. Below are setup instructions for common platforms.

Claude Code (Claude Desktop)

1. Open Claude Desktop settings

2. Navigate to the MCP servers configuration

3. Add the following configuration:

{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}

4. Save the configuration and restart Claude Desktop

5. The MCP server tools will now be available in Claude Code

Cline (VS Code Extension)

1. Install the Cline extension from the VS Code Marketplace

2. Open VS Code settings (Ctrl/Cmd + ,)

3. Search for "Cline: MCP Servers"

4. Add the MCP server configuration:

{
  "cline.mcpServers": [
    {
      "name": "api-docs",
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  ]
}

5. Save the settings and reload VS Code

6. The MCP tools will be available in Cline

Kilo Code

1. Open Kilo Code settings

2. Navigate to MCP servers configuration

3. Add the server configuration:

{
  "mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}

4. Save and restart Kilo Code

5. The MCP server will be automatically connected

Windsurf (Codeium)

1. Open Windsurf settings

2. Navigate to Extensions → MCP

3. Add a new MCP server with the following configuration:

• Name: api-docs

• Command: node

• Arguments: d:/My works/api-docs-mcp/index.js

• Environment Variables:

  • API_DEFINITIONS_DIR = D:/My works/DauTuCong/Frontend/src/assets/api-definitions

4. Save the configuration

5. Restart Windsurf to activate the MCP server

Cursor

1. Open Cursor settings (Ctrl/Cmd + ,)

2. Navigate to the MCP servers section

3. Add the following configuration:

{
  "cursor.mcpServers": {
    "api-docs": {
      "command": "node",
      "args": ["d:/My works/api-docs-mcp/index.js"],
      "env": {
        "API_DEFINITIONS_DIR": "D:/My works/DauTuCong/Frontend/src/assets/api-definitions"
      }
    }
  }
}

4. Save the settings

5. Reload Cursor to apply the changes

General MCP Configuration Notes

• Path Adjustments: Update the file paths in the configurations above to match your actual project location

• Environment Variable: The API_DEFINITIONS_DIR environment variable should point to your API definitions directory

• Permissions: Ensure the AI agent has permission to execute the MCP server

• Troubleshooting: If the MCP server doesn't connect, check:

  • Node.js is installed and accessible

  • The file paths are correct

  • The API definitions directory exists and contains valid JSON files

  • Check the agent's logs for connection errors

Verifying MCP Connection

After setting up the MCP server with any AI agent, you can verify the connection by:

1. Asking the AI agent to list available tools

2. Requesting to list all APIs using the list_apis tool

3. Checking if the agent can access API definitions and schemas

If successful, the AI agent should be able to query API definitions, search endpoints, and retrieve schema information using the MCP tools.

Usage

Running the Server

Start the MCP server:

npm start

The server runs on stdio and can be connected to by any MCP-compatible client.

Available Tools

1. list_apis

List all available API definitions with their titles and versions.

Parameters: None

Example Response:

[
  {
    "name": "auth",
    "title": "Authentication API",
    "version": "v1",
    "filename": "auth.swagger.json"
  }
]

2. get_api_details

Get detailed information about a specific API definition.

Parameters:

• name (required): API name (e.g., "auth", "projects", "users")

Example:

{
  "name": "auth"
}

3. list_tags

List all tags across all API definitions.

Parameters: None

Example Response:

["Auth", "Projects", "Users"]

4. search_by_tag

Search for endpoints by tag name.

Parameters:

• tag (required): Tag name to search for

Example:

{
  "tag": "Auth"
}

5. search_by_path

Search for endpoints by path pattern (supports regex).

Parameters:

• pattern (required): Path pattern to search for (e.g., "/api/Auth", "/api/.*")

Example:

{
  "pattern": "/api/Auth"
}

6. get_endpoint

Get detailed information about a specific endpoint.

Parameters:

• api (required): API name (e.g., "auth", "projects")

• path (required): Endpoint path (e.g., "/api/Auth/login")

• method (required): HTTP method (GET, POST, PUT, DELETE, etc.)

Example:

{
  "api": "auth",
  "path": "/api/Auth/login",
  "method": "POST"
}

7. get_schema

Get detailed information about a specific schema.

Parameters:

• api (required): API name (e.g., "auth", "projects")

• schemaName (required): Schema name (e.g., "LoginCommand", "AuthResponseDto")

Example:

{
  "api": "auth",
  "schemaName": "LoginCommand"
}

8. list_schemas

List all schemas in a specific API definition.

Parameters:

• api (required): API name (e.g., "auth", "projects")

Example:

{
  "api": "auth"
}

Configuration

The API definitions directory can be configured via environment variable:

export API_DEFINITIONS_DIR="path/to/your/api-definitions"
npm start

Or set it inline:

API_DEFINITIONS_DIR="path/to/your/api-definitions" npm start

If not set, it defaults to D:\My works\DauTuCong\Frontend\src\assets\api-definitions.

API Definitions Structure

The MCP server expects OpenAPI/Swagger JSON files in the configured directory. Each file should follow the OpenAPI 3.0 specification format.

Directory Structure Example

api-definitions/
├── auth.swagger.json
├── projects.swagger.json
├── users.swagger.json
└── ...

Sample API Definition File Structure

Each API definition file should contain the following structure:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Authentication API",
    "version": "v1",
    "description": "API for authentication operations"
  },
  "tags": [
    {
      "name": "Auth",
      "description": "Authentication endpoints"
    }
  ],
  "paths": {
    "/api/Auth/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "User login",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginCommand"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful login",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponseDto"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LoginCommand": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        },
        "required": ["username", "password"]
      },
      "AuthResponseDto": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserDto"
          }
        }
      },
      "UserDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      }
    }
  }
}

Key Components

1. Info Section: Contains API metadata (title, version, description)

2. Tags: Categorize endpoints for better organization

3. Paths: Define all API endpoints with their HTTP methods

4. Components/Schemas: Define reusable data models and request/response structures

File Naming Convention

• Use descriptive names: auth.swagger.json, projects.swagger.json

• Keep names lowercase and use hyphens for multi-word names

• The filename is used as the API identifier (without the .swagger.json extension)

Supported Features

The MCP server supports:

• Multiple HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)

• Path parameters (e.g., /api/users/{id})

• Query parameters

• Request bodies with schema references

• Response schemas

• Multiple response status codes

• Tag-based endpoint categorization

Example Workflows

Find all authentication endpoints

1. Use list_tags to see available tags

2. Use search_by_tag with tag "Auth" to find all authentication endpoints

3. Use get_endpoint to get detailed information about specific endpoints

Explore a specific API

1. Use list_apis to see all available APIs

2. Use get_api_details to get an overview of a specific API

3. Use list_schemas to see all data models in that API

4. Use get_schema to get detailed information about specific schemas

Search for endpoints by path

1. Use search_by_path with pattern "/api/Auth" to find all auth-related endpoints

2. Use search_by_path with pattern "/api/.*" to find all endpoints

3. Use get_endpoint to get detailed information about specific endpoints

Error Handling

The server returns error messages in the following cases:

• API definition not found

• Endpoint not found

• Schema not found

• Invalid file format

• File read errors

All errors are returned with an isError: true flag in the response.

License

MIT