How do I use Custom OpenAPI MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Custom OpenAPI MCP Server Show me all authentication endpoints" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Custom OpenAPI MCP Server

by ujwal-patel

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

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

Related MCP server: mcp-swagger

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

Clone and Install

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

Configure Environment (Optional)

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

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

alt text

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Available Tools

3 tools

describe_endpointA

Return summary, description, parameters & responses for one endpoint.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Endpoint path, e.g. /auth/login
`method`	Yes	HTTP verb, e.g. POST

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It only states that it 'Return[s]' information, without mentioning read-only behavior, error conditions, or any side effects. This is insufficient for transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence (8 words) that is front-loaded and free of redundant information. It efficiently conveys the core function without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description gives a general idea but lacks specifics about response structure or error handling. It is adequate given the tool's simplicity but not comprehensive enough to score higher.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters with clear descriptions and examples (e.g., /auth/login, POST). The tool description adds no additional meaning about parameters, so with 100% schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Return summary, description, parameters & responses for one endpoint.' The verb 'Return' and the specific resource 'one endpoint' make the purpose explicit, and it distinguishes from sibling tools like list_endpoints_by_tag (listing multiple endpoints) and generate_request_example (creating an example).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for a single endpoint ('for one endpoint') but does not explicitly state when to use this tool over alternatives or mention any exclusions. No direct guidance is given, so it only meets the 'implied usage' level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_request_exampleA

Create a sample JSON body for an endpoint (if it has one).

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Endpoint path
`method`	Yes	HTTP verb

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. The 'if it has one' caveat hints at conditional behavior but does not explain what happens for endpoints without a body, error behavior, or the exact output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the core action and contains no filler. It is appropriately concise for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool, the description conveys the main purpose, but without annotations or an output schema it leaves behavioral uncertainty (e.g., what happens for endpoints without a body, exact return value). Adequate but with notable gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes both parameters fully ('Endpoint path', 'HTTP verb'), and the description adds no additional parameter-level meaning. With 100% schema coverage, the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the function: generating a sample JSON body for a given endpoint. It uses a specific verb ('Create') and identifies the resource, distinguishing it from sibling list/describe tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use when a sample JSON body for an endpoint is needed. There is no explicit guidance on when not to use it or how it relates to sibling tools, though the distinct purpose is inferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_endpoints_by_tagA

List every endpoint (method + description) under a given tag.

ParametersJSON Schema

Name	Required	Description	Default
`tag`	Yes	OpenAPI tag, e.g. Authentication

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It states that the tool returns a list of methods and descriptions for all endpoints under a tag, which is transparent about the output shape. However, it does not mention any potential limitations (e.g., pagination, authentication requirements) or confirm non-destructive behavior beyond the word "List". The description provides basic transparency but no deeper behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys the essential information without any filler. It is appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one well-documented parameter and no output schema, the description is complete: it states the input (tag) and the output (method + description for each endpoint). It lacks only optional details like pagination or ordering, but these are not essential for understanding the tool's core function. Given the presence of siblings, the description is sufficient to guide selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully documents the sole parameter "tag" with a clear description and example. Since schema coverage is 100%, the description adds little beyond the schema. The tool's description refers to "under a given tag", which reinforces the parameter's meaning but does not add new semantic detail. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (List) and the resource (every endpoint under a given tag), and specifies the returned fields (method + description), distinguishing it from the sibling tools describe_endpoint and generate_request_example.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a use case (listing endpoints by tag) but offers no explicit when-to-use guidance or alternatives, and fails to distinguish when to use this vs describe_endpoint or generate_request_example. No exclusions or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.0.0Aug 2, 2026
- First observeddescribe_endpoint
- First observedgenerate_request_example
- First observedlist_endpoints_by_tag

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-08-02 22:25 across 3 tools

Disambiguation5/5

Each tool serves a distinct purpose: listing endpoints under a tag, describing a specific endpoint, and generating a request example. There's no overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow a clear verb_noun pattern in snake_case: list_endpoints_by_tag, describe_endpoint, generate_request_example. This is perfectly consistent.

Tool Count4/5

Three tools is on the low end but still within the expected range for a focused server. It feels slightly thin for general OpenAPI exploration, but each tool earns its place.

Completeness3/5

The set covers tagged endpoint listing, detailed endpoint descriptions, and request example generation, but lacks a way to list available tags or all endpoints without a tag. This is a notable gap that could hinder agents unfamiliar with the API structure.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Orbit A
ai.buildwithorbit
Turn any task into the right API calls: discover, evaluate, and integrate public APIs.
Developer Tools API Testing
21
surf A
tech.geckovision
Point Gecko at an OpenAPI spec; get first-call-correct, auth-hidden agent tools.
API Testing Developer Tools
226
mcp-server AOAuth
com.httpstatus
AI-callable tools for API mocking, testing, monitoring, security, and automation.
API Testing Testing & QA Tools App Automation
92
mcpOAuth
com.vibgrate
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Security Monitoring
2

Related MCP Servers

Swagger Navigator MCP Server
API Testing Developer Tools Documentation Access
aaydin-tr
A
license
Not graded
quality
C
maintenance
Enables AI assistants to discover, search, and interact with REST APIs by parsing OpenAPI/Swagger specifications with intelligent fuzzy search across endpoints, supporting both local and remote API sources.
Updated 3 months ago (2026-06-25 09:19 UTC)
6 npm
2
MIT
mcp-swagger
awssam
A
license
A
quality
D
maintenance
Exposes Swagger/OpenAPI API documentation to AI models, enabling exploration, search, and interaction with endpoints, schemas, and execution of API calls.
Updated 5 months ago (2026-04-16 22:47 UTC)
14
1 npm
2
MIT
OpenAPI MCP Server
API Testing Developer Tools AI & Machine Learning
lotusbaba
F
license
Not graded
quality
D
maintenance
Dynamically exposes any OpenAPI/Swagger API as tools for AI assistants, automatically generating MCP tools from OpenAPI specs with authentication support.
Updated a year ago (2025-07-28 20:08 UTC)
-
Open API MCP Server
API Testing Documentation Access Developer Tools
HaoYan-A
A
license
Not graded
quality
F
maintenance
Provides AI assistants with access to OpenAPI specifications, enabling API discovery, schema retrieval, and direct API execution with support for OAuth 2.0 and other authentication methods.
Updated a year ago (2025-10-29 07:50 UTC)
7 npm
1
MIT

Custom OpenAPI MCP Server

Features

Tools Provided

1. list_endpoints_by_tag

2. describe_endpoint

3. generate_request_example

Installation

Prerequisites

Quick Start

GitHub Copilot Integration

Claude Desktop Integration

Configuration

Environment Variables

Supported OpenAPI Sources

Example API URLs

Usage Examples

Architecture

Core Components

Example of current configration

Troubleshooting

Common Issues

Validation

Contributing

License

Acknowledgments

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

1. `list_endpoints_by_tag`

2. `describe_endpoint`

3. `generate_request_example`