How do I use Open API 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., "@Open API MCP Server list APIs with tag users" 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.

Open API MCP Server

by HaoYan-A

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Open API MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to OpenAPI specifications, supporting OAuth 2.0 authentication flows.

Features

📖 OpenAPI Support: Load and parse OpenAPI 2.0, 3.0, and 3.1 specifications
🔐 OAuth 2.0 Authentication: Full support for Password, Client Credentials, and Authorization Code flows
🔑 Multiple Auth Methods: API Key, Bearer Token, Basic Auth, and OAuth 2.0
🔍 Smart Search: Search and filter API endpoints by path, method, tags, or keywords
📝 Detailed Schemas: Get complete request/response schemas for any endpoint
🚀 API Execution: Call APIs directly with automatic authentication
📊 Request Logging: Track all API calls with detailed logs

Related MCP server: OpenAPI MCP Server

Installation

Option 1: Using npx (Recommended)

No installation required! Use npx to run directly:

npx @yanhao-an/open-api-mcp

Option 2: Global Installation

npm install -g @yanhao-an/open-api-mcp
open-api-mcp

Option 3: From Source (Development)

git clone https://github.com/HaoYan-A/open-api-mcp.git
cd open-api-mcp
npm install
npm run build
npm start

Configuration

Create a .env file in the project root:

# Required: OpenAPI Specification URL
OPENAPI_SPEC_URL=http://127.0.0.1/v3/api-docs

# Authentication Mode
# Options: none, apiKey, bearer, basic, oauth2
AUTH_MODE=oauth2

# OAuth 2.0 Configuration (if AUTH_MODE=oauth2)
OAUTH_FLOW=clientCredentials
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_SCOPE=read write

# Logging
LOG_LEVEL=info
LOG_REQUESTS=true
LOG_RESPONSES=true

Authentication Modes

1. OAuth 2.0 - Client Credentials Flow

Best for machine-to-machine communication:

AUTH_MODE=oauth2
OAUTH_FLOW=clientCredentials
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_SCOPE=api.access

2. OAuth 2.0 - Password Flow

For username/password authentication:

AUTH_MODE=oauth2
OAUTH_FLOW=password
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_USERNAME=user@example.com
OAUTH_PASSWORD=your-password
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_SCOPE=read write

3. OAuth 2.0 - Authorization Code Flow

For user authorization with redirect:

AUTH_MODE=oauth2
OAUTH_FLOW=authorizationCode
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_AUTH_URL=https://auth.example.com/oauth/authorize
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_REDIRECT_URI=http://localhost:3000/callback
OAUTH_CODE=<authorization-code-from-redirect>

4. API Key Authentication

AUTH_MODE=apiKey
API_KEY=your-api-key
API_KEY_HEADER=Authorization
API_KEY_PREFIX=Bearer

5. Bearer Token

AUTH_MODE=bearer
BEARER_TOKEN=your-bearer-token

6. Basic Authentication

AUTH_MODE=basic
BASIC_AUTH_USER=username
BASIC_AUTH_PASS=password

Usage

Running the Server

# Development mode
npm run dev

# Production mode
npm start

# Test with MCP Inspector
npm run inspect

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "open-api": {
      "command": "npx",
      "args": ["-y", "@yanhao-an/open-api-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "http://127.0.0.1/v3/api-docs",
        "AUTH_MODE": "oauth2",
        "OAUTH_FLOW": "clientCredentials",
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token"
      }
    }
  }
}

Or if you installed it globally:

{
  "mcpServers": {
    "open-api": {
      "command": "open-api-mcp",
      "args": [],
      "env": {
        "OPENAPI_SPEC_URL": "http://127.0.0.1/v3/api-docs",
        "AUTH_MODE": "oauth2",
        "OAUTH_FLOW": "clientCredentials",
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token"
      }
    }
  }
}

MCP Tools

1. `listApi`

List all available API endpoints with optional filtering.

Parameters:

tag (optional): Filter by tag name
limit (optional): Maximum results (default: 50)
offset (optional): Skip results (default: 0)

Example:

{
  "tag": "users",
  "limit": 20
}

2. `searchApi`

Search for API endpoints by keyword.

Parameters:

query (required): Search query
method (optional): HTTP method filter
tag (optional): Tag filter

Example:

{
  "query": "user",
  "method": "GET"
}

3. `getApiSchema`

Get detailed schema for a specific endpoint.

Parameters:

path (required): API path (e.g., /users/{id})
method (required): HTTP method

Example:

{
  "path": "/api/users/{id}",
  "method": "GET"
}

4. `callApi`

Execute an API request with authentication.

Parameters:

path (required): API path
method (required): HTTP method
params (optional): Query parameters
body (optional): Request body
headers (optional): Additional headers

Example:

{
  "path": "/api/users",
  "method": "POST",
  "body": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

5. `getAuthStatus`

Get current authentication status and configuration.

6. `getApiInfo`

Get OpenAPI document information (title, version, base URL, tags).

Project Structure

open-api-mcp/
├── src/
│   ├── auth/                 # Authentication management
│   │   ├── auth-manager.ts   # Main auth manager
│   │   ├── oauth2-handler.ts # OAuth 2.0 orchestrator
│   │   ├── token-manager.ts  # Token storage
│   │   └── flows/            # OAuth 2.0 flow implementations
│   ├── openapi/              # OpenAPI document handling
│   │   ├── loader.ts         # Load from URL
│   │   ├── parser.ts         # Parse and index
│   │   └── cache.ts          # Document caching
│   ├── api/                  # API execution
│   │   └── caller.ts         # HTTP client with auth
│   ├── tools/                # MCP tools
│   │   └── index.ts          # Tool registration
│   ├── logger.ts             # Logging utility
│   ├── types.ts              # TypeScript types
│   └── index.ts              # Main entry point
├── package.json
├── tsconfig.json
└── .env

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run watch

# Test with inspector
npm run inspect

OAuth 2.0 Flow Details

Token Management

Automatic Refresh: Tokens are automatically refreshed when expired
Token Caching: Valid tokens are cached to reduce auth requests
Expiry Buffer: Tokens are refreshed 60 seconds before expiry

Flow Selection Guide

Client Credentials: Best for server-to-server, no user context
Password Flow: For trusted applications with username/password
Authorization Code: For user-authorized access with redirect flow

Logging

The server provides detailed logging for debugging:

# Log levels: debug, info, warn, error
LOG_LEVEL=debug

# Enable/disable request logging
LOG_REQUESTS=true

# Enable/disable response logging
LOG_RESPONSES=true

Request logs include:

Timestamp
HTTP method and URL
Authentication mode
Request parameters and body
Response status and data
Request duration

Troubleshooting

"Failed to load OpenAPI document"

Verify OPENAPI_SPEC_URL is correct and accessible
Check network connectivity
Ensure the URL returns valid OpenAPI JSON/YAML

"OAuth 2.0 flow failed"

Verify OAuth credentials (client ID, secret)
Check token URL is correct
Ensure required scopes are available
Review server logs for specific error messages

"Token refresh failed"

Verify refresh token is valid
Check if refresh tokens are supported by the auth server
Try re-authenticating to get a new token

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

This server cannot be deployed

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

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

API.market MCP GatewayOAuth
io.github.Noveum
Connect AI agents to 580+ APIs with OAuth or API-key auth. Hosted gateway; API pricing varies.
Agent Orchestration
1
Orbit A
ai.buildwithorbit
Turn any task into the right API calls: discover, evaluate, and integrate public APIs.
Developer Tools API Testing
21
nexusOAuth
com.civic
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Agent Orchestration Developer Tools App Automation
2
ScrollportOAuth
com.scrollport
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Agent Orchestration Developer Tools
1

Related MCP Servers

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
7 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)
-
Janus MCP
Documentation Access Developer Tools
DeanWard
A
license
A
quality
D
maintenance
Enables AI assistants to understand and interact with OpenAPI specifications, providing deep insight into API structures for faster and more accurate API integration.
Updated a year ago (2025-09-03 15:27 UTC)
9
13 npm
1
MIT
mcp-openapi
API Testing Developer Tools
avidianity
A
license
Not graded
quality
A
maintenance
Enables AI agents to discover, search, and call any REST API described by an OpenAPI or Swagger document. Supports multiple API endpoints with authentication and parameter handling.
Updated 2 months ago (2026-07-27 20:07 UTC)
7 npm
MIT

Open API MCP Server

Features

Installation

Option 1: Using npx (Recommended)

Option 2: Global Installation

Option 3: From Source (Development)

Configuration

Authentication Modes

1. OAuth 2.0 - Client Credentials Flow

2. OAuth 2.0 - Password Flow

3. OAuth 2.0 - Authorization Code Flow

4. API Key Authentication

5. Bearer Token

6. Basic Authentication

Usage

Running the Server

Using with Claude Desktop

MCP Tools

1. listApi

2. searchApi

3. getApiSchema

4. callApi

5. getAuthStatus

6. getApiInfo

Project Structure

Development

OAuth 2.0 Flow Details

Token Management

Flow Selection Guide

Logging

Troubleshooting

"Failed to load OpenAPI document"

"OAuth 2.0 flow failed"

"Token refresh failed"

License

Contributing

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-swagger

OpenAPI MCP Server

Janus MCP

mcp-openapi

1. `listApi`

2. `searchApi`

3. `getApiSchema`

4. `callApi`

5. `getAuthStatus`

6. `getApiInfo`