Name: MCP OpenAPI Connector
Author: ssossan

LABSCO SUMMARY

Useful precisely when no one has written a server for your API.

Internal APIs never get a dedicated MCP server, and they are usually the ones an agent most needs to reach. If yours has an OpenAPI spec and OAuth2, this turns it into tools without writing code — and the include and exclude filters matter more than they look, because a large spec would otherwise flood the client's tool list. The custom-tool hook covers the operations the spec describes badly.

What it is

A generic bridge between an OAuth2-protected API and an MCP client. It reads an OpenAPI or Swagger specification and generates a tool per operation, handling token acquisition and refresh itself so no separate proxy server is needed.

What you get

MCP tools generated automatically from every operation in your OpenAPI spec
Filtering over which operations become tools: OPENAPI_INCLUDE_ONLY for an allow list, OPENAPI_EXCLUDE for exclusions, OPENAPI_TOOL_PREFIX to namespace the generated names
OAuth2 client-credentials handling with token caching and automatic refresh, plus retry on authentication errors
Custom tools beyond the spec: register one in a JavaScript file with its own input schema, endpoint and method, and point CUSTOM_TOOLS_PATH at it
An interactive setup wizard (npm run setup) that collects the configuration and writes both the env file and a ready Claude Desktop config

Requirements

Client credentials for the target API — CLIENT_ID and CLIENT_SECRET — plus API_BASE_URL, AUTH_PATH for the token endpoint, and OPENAPI_SPEC_PATH pointing at a JSON spec file. The spec is not optional: without it the server only provides test and debug tools. Run with npx @ssossan/mcp-openapi-connector or install globally; the package is @ssossan/mcp-openapi-connector, 1.0.1 in package.json. Set NODE_ENV=development for verbose logging while wiring it up. MIT licensed.

Setup effort

One command plus credentials — npm install -g @ssossan/mcp-openapi-connector, then supply credentials

See installation options

USE CASES

01

Reaching an internal API nobody has built a server for

Hand it the spec and the client credentials, and get one tool per operation without writing an integration.

02

Exposing only part of a large API

Name the operations to include, or the ones to exclude, so the client's tool list stays workable.

03

Avoiding a separate proxy process

Let one process handle both MCP and the OAuth2 token lifecycle, instead of running a token proxy alongside it.

04

Covering an operation the spec describes poorly

Register a custom tool with its own schema, endpoint and method, and load it through the custom tools path.

BEFORE YOU INSTALL

What to know first

Requires

npx on PATH
CLIENT_ID in your environment
CLIENT_SECRET in your environment
API_BASE_URL in your environment
AUTH_PATH in your environment
OPENAPI_SPEC_PATH in your environment

Where it runs

All 3 documented setups run the server on your machine.

INSTALLATION

Connect your client

Server setup

TERMINAL

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

MCP Clients

Claude Desktop — npx

CLAUDE DESKTOP — NPX · JSON

{
  "mcpServers": {
    "openapi-connector": {
      "command": "npx",
      "args": [
        "@ssossan/mcp-openapi-connector"
      ],
      "env": {
        "CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "API_BASE_URL": "<YOUR_API_BASE_URL>",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "<YOUR_OPENAPI_SPEC_PATH>"
      }
    }
  }
}

Claude Desktop — global install

CLAUDE DESKTOP — GLOBAL INSTALL · JSON

{
  "mcpServers": {
    "openapi-connector": {
      "command": "mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "API_BASE_URL": "<YOUR_API_BASE_URL>",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "<YOUR_OPENAPI_SPEC_PATH>"
      }
    }
  }
}

Claude Desktop — local build

CLAUDE DESKTOP — LOCAL BUILD · JSON

{
  "mcpServers": {
    "openapi-connector": {
      "command": "node",
      "args": [
        "<YOUR_PATH_TO_MCP_OPENAPI_CONNECTOR>/dist/mcp-openapi-connector.js"
      ],
      "cwd": "<YOUR_PATH_TO_MCP_OPENAPI_CONNECTOR>",
      "env": {
        "CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "API_BASE_URL": "<YOUR_API_BASE_URL>",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "<YOUR_OPENAPI_SPEC_PATH>"
      }
    }
  }
}

MCP OpenAPI Connector