api-to-mcp

Turn any API into an MCP server in one command.

Connect OpenAPI REST and GraphQL APIs directly to Claude, Cursor, or any MCP client — no code required.

npx @sgaluza/api-to-mcp rest https://api.example.com/openapi.yaml

OpenAPI spec / GraphQL schema
        │
        ▼
  api-to-mcp (stdio)
        │
        ├── tool: getUser
        ├── tool: listIssues
        ├── tool: createIssue
        └── tool: ...
        │
        ▼
  Claude / Cursor / any MCP client

---

Table of Contents

• Quick start
• OpenAPI / REST
  • Authentication
  • JWT password authentication
  • Base URL override
  • Config file
  • Filtering tools
  • Pre-binding parameters
  • Environment variables
  • MCP client configuration
• GraphQL
• How it works
• License

---

Quick start

# REST — from a remote OpenAPI spec
npx @sgaluza/api-to-mcp rest https://api.example.com/openapi.yaml

# REST — from a local file
npx @sgaluza/api-to-mcp rest ./openapi.yaml

# GraphQL — from an endpoint (auto-introspects schema)
npx @sgaluza/api-to-mcp graphql https://api.example.com/graphql

# GraphQL — from a local SDL file
npx @sgaluza/api-to-mcp graphql ./schema.graphql

Every operationId (REST) or operation name (GraphQL) becomes an MCP tool. If an operation has no operationId, a name is generated from the method and path (e.g. GET /users/{id} → get_users_id).

---

OpenAPI / REST

Authentication

Pass credentials via --header flags, environment variables, or a config file.

Header flags — added to every outgoing request:

npx @sgaluza/api-to-mcp rest ./openapi.yaml \
  -H "X-API-Key: pk_live_xxx" \
  -H "X-Workspace-Id: ws_abc"

Environment variables:

# Bearer token → Authorization: Bearer <token>
API2MCP_BEARER_TOKEN=eyJhbG... npx @sgaluza/api-to-mcp rest ./openapi.yaml

# API key — header name detected from securitySchemes in the spec
API2MCP_API_KEY=pk_live_xxx npx @sgaluza/api-to-mcp rest ./openapi.yaml

# Raw Authorization header value (e.g. Linear API keys use "lin_api_xxx" without Bearer)
API2MCP_AUTH_TOKEN=lin_api_xxx npx @sgaluza/api-to-mcp rest ./openapi.yaml

Auth resolution order (highest priority wins):

Priority	Source	Result
1 (highest)	--header / -H flags	Used as-is
2	API2MCP_BEARER_TOKEN env	Authorization: Bearer <token>
3	API2MCP_API_KEY env	Header name from securitySchemes in spec
4	API2MCP_AUTH_TOKEN env	Raw Authorization: <token>
5 (lowest)	auth in config file	Overridden by any env var above

Legacy aliases OPENAPI_BEARER_TOKEN, OPENAPI_API_KEY, OPENAPI_SPEC_URL are still supported.

---

JWT password authentication

Some APIs authenticate with a username/password login endpoint that returns a short-lived JWT. api-to-mcp handles the full token lifecycle automatically:

• Lazy login — token is fetched on the first request, not at startup
• Auto-refresh — token is proactively refreshed 5 minutes before expiry
• 401 retry — if the server returns 401, the token is force-refreshed and the request is retried once
• Deduplication — concurrent requests share a single in-flight login call

npx @sgaluza/api-to-mcp rest https://api.example.com/openapi.yaml \
  --auth-type jwt-password \
  --auth-login-url https://api.example.com/auth/login \
  --auth-username-field userName \
  --auth-password-field password \
  --auth-token-path jwt \
  --auth-refresh-url https://api.example.com/auth/refresh-token

Flag	Env variable	Default	Description
--auth-type jwt-password	API2MCP_AUTH_TYPE	—	Enable JWT password auth
--auth-login-url <url>	API2MCP_AUTH_LOGIN_URL	—	Login endpoint (POST)
--auth-username-field <field>	API2MCP_AUTH_USERNAME_FIELD	username	Request body field for username
--auth-password-field <field>	API2MCP_AUTH_PASSWORD_FIELD	password	Request body field for password
--auth-token-path <path>	API2MCP_AUTH_TOKEN_PATH	token	Path to JWT in login response: simple (jwt), dot-path (data.token), or JSONPath ($.response.jwt)
--auth-refresh-url <url>	API2MCP_AUTH_REFRESH_URL	—	Optional token refresh endpoint (GET)

Credentials are passed via environment variables (never as CLI flags):

API2MCP_USERNAME=alice API2MCP_PASSWORD=s3cret \
  npx @sgaluza/api-to-mcp rest https://api.example.com/openapi.yaml \
  --auth-type jwt-password \
  --auth-login-url https://api.example.com/auth/login

Config file:

auth:
  type: jwt-password
  loginUrl: https://api.example.com/auth/login
  usernameField: userName       # default: username
  passwordField: password       # default: password
  tokenPath: jwt                # default: token
  refreshUrl: https://api.example.com/auth/refresh-token

MCP client config (credentials injected via env):

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y", "@sgaluza/api-to-mcp", "rest",
        "https://api.example.com/openapi.yaml",
        "--auth-type", "jwt-password",
        "--auth-login-url", "https://api.example.com/auth/login",
        "--auth-username-field", "userName",
        "--auth-token-path", "jwt"
      ],
      "env": {
        "API2MCP_USERNAME": "alice",
        "API2MCP_PASSWORD": "s3cret"
      }
    }
  }
}

---

Base URL override

Override the base URL extracted from servers[0].url in the spec. Useful when the spec is hosted on a different domain than the API (e.g. staging spec + production API):

npx @sgaluza/api-to-mcp rest https://staging.example.com/openapi.json \
  --base-url https://api.example.com

Flag	Env variable	Config key	Description
--base-url <url>	API2MCP_BASE_URL	options.baseUrl	Override base URL from spec's servers[0].url

---

Config file

Store your spec URL, auth, and options in a file instead of passing flags every time.

Auto-discovery: api-to-mcp.yml, api-to-mcp.yaml, or api-to-mcp.json in the current directory.

Explicit path: --config path/to/config.yml

# api-to-mcp.yml
spec: https://api.example.com/openapi.yaml

auth:
  bearer: eyJhbG...          # → Authorization: Bearer <token>
  # apiKey: pk_live_xxx      # → header from securitySchemes
  # token: lin_api_xxx       # → raw Authorization header
  headers:                   # arbitrary headers (lowest priority)
    X-Workspace-Id: ws_abc

options:
  readonly: true             # only GET/HEAD operations
  baseUrl: https://api.example.com  # override spec's servers[0].url
  only:
    - getIssue
    - listIssues
  exclude:
    - deleteEverything
  bind:
    teamId: TEAM_ABC

Priority: CLI flags > environment variables > config file.

---

Filtering tools

Read-only mode — expose only GET and HEAD operations:

npx @sgaluza/api-to-mcp rest ./openapi.yaml --readonly

Whitelist — expose only specific operations by operationId:

npx @sgaluza/api-to-mcp rest ./openapi.yaml \
  --only "getIssue,listIssues,getProject"

Blacklist — expose everything except specific operations:

npx @sgaluza/api-to-mcp rest ./openapi.yaml \
  --exclude "deleteIssue,archiveProject,purgeWorkspace"

--only and --exclude are mutually exclusive.

---

Overriding tool descriptions

Sometimes an OpenAPI spec has poor or missing descriptions on generated tools (e.g. undocumented enum values, ambiguous parameter names). You can override any tool's description without modifying the spec.

Config file:

# api-to-mcp.yml
overrides:
  post_api_quote_items: "Get paginated quotes. IMPORTANT: sorter.property must be PascalCase (Created, Number, Client, Status), sorter.direction must be Asc or Desc."
  getUser: "Fetch a single user by ID."

Environment variable (takes priority over config file):

API2MCP_OVERRIDE_post_api_quote_items="Get paginated quotes. IMPORTANT: sorter.property must be PascalCase..."

Only the description field is replaced — the tool name, input schema, and all other properties remain unchanged.

---

Pre-binding parameters

Pre-bind a path or query parameter to a fixed value with --bind key=value. The parameter is removed from the MCP tool's input schema — the bridge injects it automatically on every call.

Useful when you want Claude to operate within a specific workspace, team, or project without being able to change it.

# Always query within team TEAM_ABC
npx @sgaluza/api-to-mcp rest ./openapi.yaml \
  --bind "teamId=TEAM_ABC"

# Scope to a specific project
npx @sgaluza/api-to-mcp rest ./openapi.yaml \
  --bind "projectId=PROJ_XYZ" \
  --bind "env=production"

The bridge warns if a bound key is not found in any tool (likely a typo):

Warning: --bind key 'temId' not found in any tool. Check for typos.

Note: The body parameter (POST/PUT/PATCH request bodies) cannot be pre-bound.

---

Environment variables

Variable	Description
API2MCP_SPEC_URL	OpenAPI spec URL or file path (alternative to positional argument)
API2MCP_BASE_URL	Override base URL from spec's servers[0].url
API2MCP_BEARER_TOKEN	Bearer token → Authorization: Bearer <token>
API2MCP_API_KEY	API key → header name from securitySchemes
API2MCP_AUTH_TOKEN	Raw Authorization header value
API2MCP_AUTH_TYPE	Auth type — currently supports jwt-password
API2MCP_AUTH_LOGIN_URL	JWT login endpoint URL
API2MCP_USERNAME	Username for JWT password auth
API2MCP_PASSWORD	Password for JWT password auth
API2MCP_AUTH_USERNAME_FIELD	Request body field for username (default: username)
API2MCP_AUTH_PASSWORD_FIELD	Request body field for password (default: password)
API2MCP_AUTH_TOKEN_PATH	Path to JWT in login response (default: token)
API2MCP_AUTH_REFRESH_URL	JWT refresh endpoint URL
API2MCP_OVERRIDE_<toolName>	Override description for a specific tool (e.g. API2MCP_OVERRIDE_getFoo="Custom description")

---

MCP client configuration

Add to your mcp_settings.json, claude_desktop_config.json, or equivalent:

Minimal:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "@sgaluza/api-to-mcp", "rest", "https://api.example.com/openapi.yaml"],
      "env": {
        "API2MCP_API_KEY": "pk_live_xxx"
      }
    }
  }
}

GitHub — read-only with bearer token:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "@sgaluza/api-to-mcp", "rest",
        "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--readonly"
      ],
      "env": {
        "API2MCP_BEARER_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Linear — scoped to a team, specific operations:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y", "@sgaluza/api-to-mcp", "rest",
        "https://api.linear.app/rest/openapi.yaml",
        "--bind", "teamId=TEAM_ABC",
        "--only", "listIssues,getIssue,createIssue,updateIssue"
      ],
      "env": {
        "API2MCP_BEARER_TOKEN": "lin_api_xxx"
      }
    }
  }
}

Using a config file:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "@sgaluza/api-to-mcp", "rest", "--config", "/path/to/api-to-mcp.yml"]
    }
  }
}

---

GraphQL

# Auto-introspect schema from a GraphQL endpoint
npx @sgaluza/api-to-mcp graphql https://api.example.com/graphql

# Load schema from a local SDL file
npx @sgaluza/api-to-mcp graphql ./schema.graphql

All queries and mutations become MCP tools. The same flags apply: --header, --readonly (queries only, no mutations), --only, --exclude, --bind, --config.

MCP client config:

{
  "mcpServers": {
    "my-graphql-api": {
      "command": "npx",
      "args": ["-y", "@sgaluza/api-to-mcp", "graphql", "https://api.example.com/graphql"],
      "env": {
        "API2MCP_BEARER_TOKEN": "eyJhbG..."
      }
    }
  }
}

---

How it works

Each API operation is converted to an MCP tool at startup:

REST (OpenAPI):

OpenAPI	MCP tool
operationId	Tool name (fallback: {method}_{path})
summary + description	Tool description
Path params {id}	Required input parameters
Query params	Optional input parameters
requestBody (application/json)	body parameter
servers[0].url	Base URL for all requests

GraphQL:

GraphQL	MCP tool
Query / Mutation name	Tool name
Description from schema	Tool description
Arguments	Input parameters
Return type fields	Included in description

When Claude calls a tool, the bridge:

1. Substitutes path parameters into the URL template
2. Appends query parameters
3. Serialises body as JSON (for POST/PUT/PATCH)
4. Injects pre-bound values and auth headers
5. Returns the response body as the tool result

---

License

MIT