OpenAPI MCP Server (JavaScript)

A pure JavaScript implementation of a Model Context Protocol (MCP) server that transforms OpenAPI 3.x specifications into MCP tools, enabling Large Language Models (LLMs) to interact with REST APIs through the standardized MCP protocol.

Features

• Pure JavaScript: Built with Node.js and ES modules

• OpenAPI 3.x Support: Automatically converts OpenAPI specifications into MCP tools

• Bearer Token Authentication: Supports bearer token authentication for API requests

• All HTTP Methods: Supports GET, POST, PUT, DELETE, PATCH, OPTIONS, and HEAD

• Configurable Base URL: Accept custom API base URLs

• Parameter Validation: Validates tool parameters against OpenAPI schemas

• Error Handling: Comprehensive error handling and reporting

• CLI Interface: Easy-to-use command-line interface

Installation

npm install

Usage

Quick Start

1. Validate your OpenAPI specification:

node src/index.js validate -s UserQueueList.json

2. Start the MCP server:

node src/index.js serve -s UserQueueList.json -b https://api.example.com -t your-bearer-token

Command Line Options

serve - Start the MCP server

node src/index.js serve [options]

Options:
  -s, --spec <path>       Path to OpenAPI specification file (required)
  -b, --base-url <url>    Base URL for API requests
  -t, --token <token>     Bearer token for authentication
  --timeout <ms>          Request timeout in milliseconds (default: 30000)
  --transport <type>      Transport type (stdio or http, default: stdio)
  --http-port <port>      HTTP server port (when using http transport, default: 3000)
  --http-host <host>      HTTP server host (when using http transport, default: localhost)

validate - Validate OpenAPI specification

node src/index.js validate -s <path-to-spec>

info - Show server information

node src/index.js info

Environment Variables

You can use environment variables instead of command-line arguments:

export OPENAPI_BASE_URL=https://api.example.com
export OPENAPI_BEARER_TOKEN=your-bearer-token
node src/index.js serve -s UserQueueList.json

node src/index.js serve -s UserQueueList.json --transport=http --http-port=8020

Configuration

OpenAPI Specification Requirements

• Must be OpenAPI 3.x format

• JSON format (.json extension)

• Must contain at least one path/operation

• Bearer token authentication should be defined in security schemes

Example OpenAPI Security Configuration

{
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearer": []
    }
  ]
}

Tool Generation

The server automatically converts OpenAPI operations into MCP tools:

Tool Naming

1. Uses operationId if available

2. Falls back to operation summary (sanitized)

3. Last resort: {method}_{path} (sanitized)

Parameter Mapping

• Path parameters: Required string parameters

• Query parameters: Optional parameters based on OpenAPI schema

• Header parameters: Prefixed with header_

• Request body: Object properties or requestBody parameter

Example Tool

For the UserQueueList.json specification:

// Tool: ListUsers (GET /domains/~/users/list)
{
  "name": "ListUsers",
  "description": "List Basic Info on Users in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

// Tool: ListCallqueues (GET /domains/~/callqueues/list)
{
  "name": "ListCallqueues", 
  "description": "Read Basic info on Call Queues in Domain",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

MCP Integration

Using with Claude Desktop

Stdio Transport (Default)

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

{
  "mcpServers": {
    "openapi-server": {
      "command": "node",
      "args": [
        "/path/to/your/project/src/index.js",
        "serve",
        "-s", "/path/to/UserQueueList.json",
        "-b", "https://your-api-domain.com",
        "-t", "your-bearer-token"
      ]
    }
  }
}

HTTP Transport

For HTTP transport, configure the server URL instead:

{
  "mcpServers": {
    "openapi-server": {
      "url": "http://localhost:3000/message"
    }
  }
}

Then start the server separately:

node src/index.js serve -s UserQueueList.json --transport http --http-port 3000

Tool Responses

The server returns structured JSON responses:

Success Response:

{
  "status": 200,
  "statusText": "OK",
  "data": {
    // API response data
  }
}

Error Response:

{
  "error": true,
  "status": 404,
  "statusText": "Not Found",
  "message": "Domain not found",
  "data": {
    "code": 404,
    "message": "Domain example does not exist"
  }
}

Transport Protocols

Stdio Transport

• Default transport method

• Uses standard input/output streams for communication

• Best for integration with Claude Desktop and other MCP clients

• Automatic process management

HTTP Transport

• Uses HTTP Server-Sent Events (SSE) for communication

• Allows remote connections and debugging

• Useful for development and testing

• Configurable host and port

API Examples

Based on the UserQueueList.json specification:

List Users

// Tool call
{
  "name": "ListUsers",
  "arguments": {}
}

// Response: Array of user objects with basic information

List Call Queues

// Tool call  
{
  "name": "ListCallqueues",
  "arguments": {}
}

// Response: Array of call queue objects with configuration

Development

Project Structure

src/
├── index.js              # CLI entry point
├── server.js             # MCP server implementation
├── openapi-processor.js  # OpenAPI specification processor
├── http-client.js        # HTTP client for API requests
└── utils.js              # Utility functions

Key Components

• MCPServer: Main MCP server class handling tool registration and execution

• OpenAPIProcessor: Parses OpenAPI specs and generates tool definitions

• HttpClient: Handles HTTP requests with authentication and error handling

• CLI: Command-line interface with validation and configuration options

Error Handling

The server provides comprehensive error handling:

• Validation Errors: Parameter validation against OpenAPI schemas

• HTTP Errors: Proper handling of API error responses

• Authentication Errors: Clear messages for auth failures

• Network Errors: Timeout and connectivity error handling

Security Considerations

• Bearer tokens are handled securely and not logged

• Request validation prevents injection attacks

• Error messages don't expose sensitive information

• HTTPS is recommended for all API communications

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Troubleshooting

Common Issues

1. "Tool not found" errors: Check that your OpenAPI spec is valid and contains the expected operations

2. Authentication failures: Verify your bearer token is correct and has proper permissions

3. Network timeouts: Increase timeout or check API endpoint availability

4. Schema validation errors: Ensure your OpenAPI spec follows 3.x standards

Debug Mode

For detailed logging, you can modify the server to enable debug output:

# The server logs to stderr for MCP compatibility
node src/index.js serve -s UserQueueList.json -b https://api.example.com -t token 2>debug.log

Validation

Always validate your OpenAPI specification before use:

node src/index.js validate -s UserQueueList.json

This will show:

• ✅ Validation status

• 📄 Specification details

• 🔧 Available tools

• 🔐 Security schemes

• 🌐 Base URL information