MCP OpenAPI Connector

A unified Model Context Protocol (MCP) server for connecting OpenAPI-based APIs with built-in authentication management. This project enables Claude Desktop, Cursor, and other MCP-compatible clients to interact with authenticated OpenAPI-based APIs without requiring separate proxy servers.

Features

Single Process Architecture: No separate proxy server needed
Built-in OAuth2 Authentication: Automatic token management and refresh
OpenAPI Integration: Automatically generate MCP tools from OpenAPI/Swagger specifications
Extensible Tool System: Easy to add custom tools and resources
Error Handling: Automatic retry and authentication error recovery
Simple Configuration: Single configuration file for all settings
Multiple API Support: Easily adapt to any OAuth2-based API

Installation

Via npm (Recommended)

npm install -g @ssossan/mcp-openapi-connector

Or use directly with npx:

npx @ssossan/mcp-openapi-connector

From Source

git clone https://github.com/ssossan/mcp-openapi-connector.git
cd mcp-openapi-connector
npm install

Quick Setup (Recommended)

Run the interactive setup wizard:

npm run setup

This will:

Collect your API configuration through interactive prompts
Generate generated/.env file with your settings
Create generated/claude-desktop-config.json for easy Claude Desktop integration
Provide step-by-step instructions for Claude Desktop configuration

Manual Configuration

Alternatively, you can set up manually:

Copy .env.example to .env:

cp .env.example .env

Edit .env with your API credentials:

CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
API_BASE_URL=https://api.example.com
AUTH_PATH=/oauth/token
OPENAPI_SPEC_PATH=./config/openapi.json

Usage

Development Mode

For development with automatic recompilation:

npm run dev

Production Mode

Build and run the compiled version:

npm run build
npm start

Claude Desktop Configuration

Add to your Claude Desktop config file:

Using npm package (Recommended):

{
  "mcpServers": {
    "openapi-connector": {
      "command": "npx",
      "args": ["@ssossan/mcp-openapi-connector"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Using global installation:

{
  "mcpServers": {
    "openapi-connector": {
      "command": "mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Using from source:

{
  "mcpServers": {
    "openapi-connector": {
      "command": "node",
      "args": ["/path/to/mcp-openapi-connector/dist/mcp-openapi-connector.js"],
      "cwd": "/path/to/mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

OpenAPI Integration

The server automatically generates tools from an OpenAPI specification. An OpenAPI specification is required for the server to function.

Place your OpenAPI spec file (JSON format) in the project
Set the path in your environment:

OPENAPI_SPEC_PATH=./config/openapi.json
OPENAPI_TOOL_PREFIX=api_  # Optional: prefix for generated tool names
OPENAPI_INCLUDE_ONLY=listItems,createItem  # Optional: only include specific operations
OPENAPI_EXCLUDE=deleteItem  # Optional: exclude specific operations

The server will automatically generate MCP tools from all operations in your OpenAPI spec. Without an OpenAPI specification, the server will only provide test/debug tools.

Custom Tools

Create custom tools by adding a JavaScript file:

export default {
  register(server) {
    server.registerCustomTool('my_tool', {
      name: 'my_tool',
      description: 'My custom tool',
      inputSchema: {
        type: 'object',
        properties: {
          param: { type: 'string', required: true }
        }
      },
      apiEndpoint: '/my-endpoint',
      method: 'POST'
    });
  }
};

Then set CUSTOM_TOOLS_PATH in your environment:

CUSTOM_TOOLS_PATH=./src/tools/my-custom-tools.ts

Publishing to npm

For maintainers:

npm run build
npm test
npm publish --access public

Development

Available Scripts

npm run dev          # Development mode with tsx
npm run build        # Compile TypeScript to JavaScript
npm start            # Build and run production version
npm run test         # Build and run test server
npm run test:dev     # Run test server in development mode
npm run typecheck    # Type check without compilation
npm run clean        # Remove build output

TypeScript Development

This project is built with TypeScript for better type safety and development experience:

Source code: src/ directory
Build output: dist/ directory
Type definitions: Automatically generated .d.ts files

Architecture

Claude Desktop ↔ MCP Server (stdio) → OpenAPI-based API
                    ↓
             TokenManager
           (OAuth2 handling)

Key Components

src/mcp-openapi-connector.ts - Main server entry point
src/lib/token-manager.ts - OAuth2 token management with caching
src/lib/saas-client.ts - HTTP client with automatic authentication
src/lib/mcp-handler.ts - MCP protocol handling and tool registration
src/lib/openapi-loader.ts - OpenAPI specification parser and tool generator
src/types/ - TypeScript type definitions

Migration from v1.x

If you're using the previous gateway-based version:

Remove the proxy server configuration
Update your Claude Desktop config to point directly to this server
Use the same environment variables (no changes needed)

Example: Using with a Generic OpenAPI-based API

See the config/openapi-example.json file for a sample OpenAPI specification that demonstrates how to structure your API for MCP integration.

Troubleshooting

Authentication Errors

Verify CLIENT_ID and CLIENT_SECRET are correct
Check AUTH_URL points to the correct OAuth2 endpoint
Ensure your credentials have the necessary scopes

Connection Issues

Check API_BASE_URL is correct
Verify network connectivity
Check server logs for detailed error messages

Debug Mode

Set NODE_ENV=development for verbose logging:

NODE_ENV=development npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Acknowledgments

Built using the Model Context Protocol SDK by Anthropic.