Custom OpenAPI MCP Server

A powerful Model Context Protocol (MCP) server that dynamically fetches and exposes OpenAPI/Swagger documentation as tools for AI assistants like GitHub Copilot and Claude. This server enables AI models to understand and interact with any REST API by automatically parsing OpenAPI specifications.

Features

• 🚀 Dynamic API Discovery: Automatically fetches and parses OpenAPI/Swagger specifications from any URL
• 🔍 Intelligent Endpoint Exploration: List and filter endpoints by tags for organized API navigation
• 📖 Detailed Documentation: Get comprehensive endpoint descriptions, parameters, and response schemas
• 💡 Smart Code Generation: Generate realistic request examples based on OpenAPI schemas
• ⚡ Real-time Integration: Works seamlessly with GitHub Copilot, Claude, and other MCP-compatible AI tools
• 🛠️ Zero Configuration: Works out of the box with sensible defaults

Tools Provided

1. list_endpoints_by_tag

Lists all endpoints grouped by OpenAPI tags, providing a high-level overview of API functionality.

Parameters:

• tag (string): OpenAPI tag name (e.g., "Authentication", "Users", "Orders")

Example Output:

GET /auth/login: Authenticate user with credentials
POST /auth/refresh: Refresh authentication token
DELETE /auth/logout: Logout and invalidate session

2. describe_endpoint

Provides detailed information about a specific endpoint including parameters, request body, and responses.

Parameters:

• path (string): API endpoint path (e.g., "/users/{id}")
• method (string): HTTP method (e.g., "GET", "POST", "PUT", "DELETE")

Example Output:

### POST /users
Create a new user account

**Parameters**
- `x-api-key` (header) **required** – string

**Request Body**
- application/json
  - schema: UserCreateRequest

**Responses**
- 201: User created successfully
- 400: Invalid request data
- 409: User already exists

3. generate_request_example

Generates sample JSON request bodies based on OpenAPI schemas, perfect for testing and development.

Parameters:

• path (string): API endpoint path
• method (string): HTTP method

Example Output:

{
  "username": "string",
  "email": "string",
  "password": "string",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "age": 0
  }
}

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• An MCP-compatible AI assistant (GitHub Copilot, Claude Desktop, etc.)

Quick Start

1. Clone and Install

   git clone <your-repo-url>
   cd custom-mcp
   npm install
   

2. Configure Environment (Optional)

   cp .env.example .env
   # Edit .env to set your API documentation URL
   

3. Test the Server

   npm start
   

GitHub Copilot Integration

{
  "mcpServers": {
    "custom-openapi": {
      "command": "node",
      "args": ["/absolute/path/to/custom-mcp/index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}

For macOS/Linux (~/.config/github-copilot/mcp.json):

{
  "servers": {
    "custom-openapi": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/custom-mcp/index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}

For Windows (%APPDATA%\github-copilot\mcp.json):

{
  "servers": {
    "custom-openapi": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\custom-mcp\\index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}

Claude Desktop Integration

Add to your Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "custom-openapi": {
      "command": "node",
      "args": ["/absolute/path/to/custom-mcp/index.js"],
      "env": {
        "API_DOCS_URL": "https://your-api.com/swagger.json"
      }
    }
  }
}

Configuration

Environment Variables

Variable	Description	Default
API_DOCS_URL	URL to OpenAPI/Swagger JSON specification	Petstore demo API

Supported OpenAPI Sources

• ✅ OpenAPI 3.0+ specifications
• ✅ Swagger 2.0 specifications
• ✅ Local files (file:// URLs)
• ✅ Remote HTTPS endpoints
• ✅ APIs with CORS enabled
• ✅ JSON and YAML formats

Example API URLs

# Petstore Demo (default)
API_DOCS_URL=https://petstore.swagger.io/v2/swagger.json

# Local development server
API_DOCS_URL=http://localhost:3000/api/docs/json

# Production API
API_DOCS_URL=https://api.yourcompany.com/v1/openapi.json

# Local file
API_DOCS_URL=file:///path/to/your/openapi.json

Usage Examples

Once integrated with your AI assistant, you can use natural language to explore APIs:

"Show me all authentication endpoints"
→ Uses list_endpoints_by_tag with tag="Authentication"

"How do I create a new user?"
→ Uses describe_endpoint for POST /users

"Generate an example request for user registration"
→ Uses generate_request_example for POST /users/register

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Assistant  │◄──►│  MCP Server      │◄──►│  OpenAPI Spec   │
│ (Copilot/Claude)│    │  (This Project)  │    │  (Remote/Local) │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Core Components

• index.js: Server bootstrap and OpenAPI spec fetching
• tools.js: MCP tool definitions and OpenAPI parsing logic
• package.json: Dependencies and project metadata
• mcp.json: Example MCP client configuration

Example of current configration

Troubleshooting

Common Issues

Server fails to start:

# Check if the API URL is accessible
curl -s "https://your-api.com/swagger.json" | jq .

# Verify Node.js version
node --version  # Should be 18+

No tools appear in AI assistant:

• Verify the absolute path in mcp.json is correct
• Restart your AI assistant after configuration changes
• Check the server logs for errors

Schema parsing errors:

• Ensure your OpenAPI spec is valid JSON/YAML
• Test with a minimal spec first
• Check for unsupported OpenAPI extensions

Validation

Test your OpenAPI specification:

# Using swagger-codegen
npx swagger-codegen-cli validate -i https://your-api.com/swagger.json

# Using online validator
curl -X POST "https://validator.swagger.io/validator/debug" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-api.com/swagger.json"}'

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with the Model Context Protocol SDK
• Inspired by the need for dynamic API exploration in AI development workflows

---