Skip to content
Back to search

mcp-openapi-server

MCP Server (Model Context Protocol) for turning OpenAPI specifications into a MCP Resource

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ivo-toby/mcp-openapi-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ivo-toby/mcp-openapi-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ivo-toby--mcp-openapi-server/badge.svg)](/listings/ivo-toby--mcp-openapi-server)

HTML

<a href="/listings/ivo-toby--mcp-openapi-server"><img src="/api/listings/ivo-toby--mcp-openapi-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Using with Claude Desktop (Stdio Transport)

No need to clone this repository. Simply configure Claude Desktop to use this MCP server:

1. Locate or create your Claude Desktop configuration file: - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. Add the following configuration:

{
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

3. Replace the environment variables with your actual API configuration: - `API_BASE_URL`: The base URL of your API - `OPENAPI_SPEC_PATH`: URL or path to your OpenAPI specification - `API_HEADERS`: Comma-separated key:value pairs for API authentication headers

Option 2: Using with HTTP Clients (HTTP Transport)

To use the server with HTTP clients:

1. No installation required! Use npx to run the package directly:

npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123" \
  --transport http \
  --port 3000

2. Interact with the server using HTTP requests:

# Initialize a session (first request)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'

# The response includes a Mcp-Session-Id header that you must use for subsequent requests
# and the InitializeResult directly in the POST response body.

# Send a request to list tools
# This also receives its response directly on this POST request.
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Open a streaming connection for other server responses (e.g., tool execution results)
# This uses Server-Sent Events (SSE).
curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

# Example: Execute a tool (response will arrive on the GET stream)
# curl -X POST http://localhost:3000/mcp \
#  -H "Content-Type: application/json" \
#  -H "Mcp-Session-Id: your-session-id" \
#  -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'

# Terminate the session when done
curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,092 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # OpenAPI MCP Server
  2. [![smithery badge](https://smithery.ai/badge/@ivo-toby/mcp-openapi-server)](https://smithery.ai/server/@ivo-toby/mcp-openapi-server)
  3. A Model Context Protocol (MCP) server that exposes OpenAPI endpoints as MCP tools, along with optional support for MCP prompts and resources. This server allows Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the MCP protocol.
  4. ## 📖 Documentation
  5. - **[User Guide](#user-guide)** - For users wanting to use this MCP server with Claude Desktop, Cursor, or other MCP clients
  6. - **[Library Usage](#library-usage)** - For developers creating custom MCP servers using this package as a library
  7. - **[Developer Guide](./docs/developer-guide.md)** - For contributors and developers working on the codebase
  8. - **[AuthProvider Guide](./docs/auth-provider-guide.md)** - Detailed authentication patterns and examples
  9. ---
  10. # User Guide
  11. This section covers how to use the MCP server as an end user with Claude Desktop, Cursor, or other MCP-compatible tools.
  12. ## Overview
  13. This MCP server can be used in two ways:
  14. 1. **CLI Tool**: Use `npx @ivotoby/openapi-mcp-server` directly with command-line arguments for quick setup
  15. 2. **Library**: Import and use the `OpenAPIServer` class in your own Node.js applications for custom implementations
  16. The server supports two transport methods:
  17. 1. **Stdio Transport** (default): For direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output.
  18. 2. **Streamable HTTP Transport**: For connecting to the server over HTTP, allowing web clients and other HTTP-capable systems to use the MCP protocol.
  19. ## Quick Start for Users
  20. ### Option 1: Using with Claude Desktop (Stdio Transport)
  21. No need to clone this repository. Simply configure Claude Desktop to use this MCP server:
  22. 1. Locate or create your Claude Desktop configuration file:
  23. - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  24. 2. Add the following configuration:
  25. ```json
  26. {
  27. "mcpServers": {
  28. "openapi": {
  29. "command": "npx",
  30. "args": ["-y", "@ivotoby/openapi-mcp-server"],
  31. "env": {
  32. "API_BASE_URL": "https://api.example.com",
  33. "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
  34. "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
  35. }
  36. }
  37. }
  38. }
  39. ```
  40. 3. Replace the environment variables with your actual API configuration:
  41. - `API_BASE_URL`: The base URL of your API
  42. - `OPENAPI_SPEC_PATH`: URL or path to your OpenAPI specification
  43. - `API_HEADERS`: Comma-separated key:value pairs for API authentication headers
  44. ### Option 2: Using with HTTP Clients (HTTP Transport)
  45. To use the server with HTTP clients:
  46. 1. No installation required! Use npx to run the package directly:
  47. ```bash
  48. npx @ivotoby/openapi-mcp-server \
  49. --api-base-url https://api.example.com \
  50. --openapi-spec https://api.example.com/openapi.json \
  51. --headers "Authorization:Bearer token123" \
  52. --transport http \
  53. --port 3000
  54. ```
  55. 2. Interact with the server using HTTP requests:
  56. ```bash
  57. # Initialize a session (first request)
  58. curl -X POST http://localhost:3000/mcp \
  59. -H "Content-Type: application/json" \
  60. -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl-client","version":"1.0.0"}}}'
  61. # The response includes a Mcp-Session-Id header that you must use for subsequent requests
  62. # and the InitializeResult directly in the POST response body.
  63. # Send a request to list tools
  64. # This also receives its response directly on this POST request.
  65. curl -X POST http://localhost:3000/mcp \
  66. -H "Content-Type: application/json" \
  67. -H "Mcp-Session-Id: your-session-id" \
  68. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  69. # Open a streaming connection for other server responses (e.g., tool execution results)
  70. # This uses Server-Sent Events (SSE).
  71. curl -N http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"
  72. # Example: Execute a tool (response will arrive on the GET stream)
  73. # curl -X POST http://localhost:3000/mcp \
  74. # -H "Content-Type: application/json" \
  75. # -H "Mcp-Session-Id: your-session-id" \
  76. # -d '{"jsonrpc":"2.0","id":2,"method":"tools/execute","params":{"name":"yourToolName", "arguments": {}}}'
  77. # Terminate the session when done
  78. curl -X DELETE http://localhost:3000/mcp -H "Mcp-Session-Id: your-session-id"
  79. ```
  80. ## Configuration Options
  81. The server can be configured through environment variables or command line arguments:
  82. ### Environment Variables
  83. - `API_BASE_URL` - Base URL for the API endpoints
  84. - `OPENAPI_SPEC_PATH` - Path or URL to OpenAPI specification
  85. - `OPENAPI_SPEC_FROM_STDIN` - Set to "true" to read OpenAPI spec from standard input
  86. - `OPENAPI_SPEC_INLINE` - Provide OpenAPI spec content directly as a string
  87. - `API_HEADERS` - Comma-separated key:value pairs for API headers
  88. - `SPEC_AUTH` - When to send the auth headers while loading the spec from a URL: `same-origin` (default), `always`, or `never` (see [Authenticated Spec URLs](#authenticated-spec-urls))
  89. - `CLIENT_CERT_PATH` - Path to client certificate PEM file for mutual TLS
  90. - `CLIENT_KEY_PATH` - Path to client private key PEM file for mutual TLS
  91. - `CA_CERT_PATH` - Path to custom CA certificate PEM file for private/internal CAs
  92. - `CLIENT_KEY_PASSPHRASE` - Passphrase for an encrypted client private key
  93. - `REJECT_UNAUTHORIZED` - Whether to reject untrusted server certificates (default: `true`)
  94. - `SERVER_NAME` - Name for the MCP server (default: "mcp-openapi-server")
  95. - `SERVER_VERSION` - Version of the server (default: "1.0.0")
  96. - `TRANSPORT_TYPE` - Transport type to use: "stdio" or "http" (default: "stdio")
  97. - `HTTP_PORT` - Port for HTTP transport (default: 3000)
  98. - `HTTP_HOST` - Host for HTTP transport (default: "127.0.0.1")
  99. - `ENDPOINT_PATH` - Endpoint path for HTTP transport (default: "/mcp")
  100. - `TOOLS_MODE` - Tools loading mode: "all" (load all endpoint-based tools), "dynamic" (load only meta-tools), or "explicit" (load only tools specified in includeTools) (default: "all")
  101. - `DISABLE_ABBREVIATION` - Disable name optimization (this could throw errors when name is > 64 chars)
  102. - `VERBOSE` - Enable operational logging (`true` by default; set to `false` to suppress non-essential logs)
  103. - `PROMPTS_PATH` - Path or URL to prompts JSON/YAML file
  104. - `PROMPTS_INLINE` - Provide prompts directly as JSON string
  105. - `RESOURCES_PATH` - Path or URL to resources JSON/YAML file
  106. - `RESOURCES_INLINE` - Provide resources directly as JSON string
  107. - `SERVER_INSTRUCTIONS` - Instructions describing how to use the server, handed to MCP clients
  108. ### Command Line Arguments
  109. ```bash
  110. npx @ivotoby/openapi-mcp-server \
  111. --api-base-url https://api.example.com \
  112. --openapi-spec https://api.example.com/openapi.json \
  113. --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  114. --spec-auth same-origin \
  115. --exclude-tag admin \
  116. --client-cert ./certs/client.pem \
  117. --client-key ./certs/client-key.pem \
  118. --name "my-mcp-server" \
  119. --server-version "1.0.0" \
  120. --transport http \
  121. --port 3000 \
  122. --host 127.0.0.1 \
  123. --path /mcp \
  124. --disable-abbreviation true \
  125. --instructions "Pages are created unapproved: approve the version once you are done." \
  126. --verbose false
  127. ```
  128. ## Mutual TLS (mTLS)
  129. If your upstream API requires client certificate authentication, you can attach TLS credentials directly to outbound requests.
  130. ```bash
  131. npx @ivotoby/openapi-mcp-server \
  132. --api-base-url https://secure-api.example.com \
  133. --openapi-spec https://secure-api.example.com/openapi.json \
  134. --client-cert ./certs/client.pem \
  135. --client-key ./certs/client-key.pem \
  136. --headers "Authorization:Bearer token123"
  137. ```
  138. This is orthogonal to HTTP-level auth, so mTLS can be combined with static headers or an `AuthProvider`.
  139. TLS-related options only apply when `--api-base-url` uses `https://`. They are also used to fetch the OpenAPI spec when `--openapi-spec` is an `https://` URL on the **same origin** (scheme, host and port) as `--api-base-url`, so a spec served by the API behind mTLS or a private CA loads with the same client certificate and CA. Spec URLs on any other origin, including redirect targets, are fetched without these settings. That way your client certificate, private CA and `--reject-unauthorized false` never apply to unrelated hosts. When TLS options are set but skipped for the spec URL, the server logs a warning and adds the reason to any load error.
  140. For private CAs or encrypted keys:
  141. ```bash
  142. npx @ivotoby/openapi-mcp-server \
  143. --api-base-url https://internal-api.example.com \
  144. --openapi-spec ./openapi.yaml \
  145. --client-cert ./certs/client.pem \
  146. --client-key ./certs/client-key.pem \
  147. --client-key-passphrase "$CLIENT_KEY_PASSPHRASE" \
  148. --ca-cert ./certs/internal-ca.pem \
  149. --reject-unauthorized false
  150. ```
  151. - `--client-cert` / `CLIENT_CERT_PATH`: client certificate PEM file
  152. - `--client-key` / `CLIENT_KEY_PATH`: client private key PEM file
  153. - `--client-key-passphrase` / `CLIENT_KEY_PASSPHRASE`: passphrase for encrypted private keys
  154. - `--ca-cert` / `CA_CERT_PATH`: custom CA bundle for private/internal certificate authorities
  155. - `--reject-unauthorized` / `REJECT_UNAUTHORIZED`: set to `false` only when you intentionally want to allow self-signed or otherwise untrusted server certificates
  156. Set `--verbose false` or `VERBOSE=false` if you want the server to stay quiet in scripts or embedded environments.
  157. ## OpenAPI Specification Loading
  158. The MCP server supports multiple methods for loading OpenAPI specifications, providing flexibility for different deployment scenarios:
  159. ### 1. URL Loading (Default)
  160. Load the OpenAPI spec from a remote URL:
  161. ```bash
  162. npx @ivotoby/openapi-mcp-server \
  163. --api-base-url https://api.example.com \
  164. --openapi-spec https://api.example.com/openapi.json
  165. ```
  166. #### Authenticated Spec URLs
  167. If the API serves its own spec behind the same auth as its endpoints, the configured `--headers` (or your `AuthProvider`) are sent with the spec request too. By default this only happens when the spec URL is on the **same origin** (scheme, host and port) as `--api-base-url`, so your credentials never reach a spec hosted elsewhere:
  168. ```bash
  169. npx @ivotoby/openapi-mcp-server \
  170. --api-base-url https://api.example.com/v1 \
  171. --openapi-spec https://api.example.com/openapi.json \
  172. --headers "Authorization:Bearer token123"
  173. ```
  174. Control this with `--spec-auth` / `SPEC_AUTH`:
  175. - `same-origin` (default): send auth headers only to a spec URL on the `--api-base-url` origin
  176. - `always`: send auth headers to the spec URL's own origin, even when it differs from the API (only for a spec host you trust with these credentials)
  177. - `never`: never send auth headers with spec requests
  178. In every mode, each redirect is checked before it is followed. A redirect to another origin, such as a pre-signed storage URL, continues **without** auth headers, and so does any redirect after that one, even if it comes back to the API origin. On a `401`/`403`, an `AuthProvider`'s `handleAuthError()` is called and the request is retried once if it returns `true`, the same as for API calls.
  179. Notes:
  180. - All configured `--headers` are sent with an authenticated spec request, not only `Authorization`.
  181. - If your `AuthProvider`'s `getAuthHeaders()` throws (for example because no token is set yet), the spec request is sent without auth and a warning is logged. If the spec then needs auth, the error includes the provider's message.
  182. - Spec URLs that embed credentials (`https://user:pass@host/...`) never get auth headers added.
  183. - Authenticated spec requests use the same HTTP client as API calls: a 30s timeout, a 50MB size limit, and a direct connection with no proxy.
  184. ### 2. Local File Loading
  185. Load the OpenAPI spec from a local file:
  186. ```bash
  187. npx @ivotoby/openapi-mcp-server \
  188. --api-base-url https://api.example.com \
  189. --openapi-spec ./path/to/openapi.yaml
  190. ```
  191. ### 3. Standard Input Loading
  192. Read the OpenAPI spec from standard input (useful for piping or containerized environments):
  193. ```bash
  194. # Pipe from file
  195. cat openapi.json | npx @ivotoby/openapi-mcp-server \
  196. --api-base-url https://api.example.com \
  197. --spec-from-stdin
  198. # Pipe from curl
  199. curl -s https://api.example.com/openapi.json | npx @ivotoby/openapi-mcp-server \
  200. --api-base-url https://api.example.com \
  201. --spec-from-stdin
  202. # Using environment variable
  203. export OPENAPI_SPEC_FROM_STDIN=true
  204. echo '{"openapi": "3.0.0", ...}' | npx @ivotoby/openapi-mcp-server \
  205. --api-base-url https://api.example.com
  206. ```
  207. ### 4. Inline Specification
  208. Provide the OpenAPI spec content directly as a command line argument:
  209. ```bash
  210. npx @ivotoby/openapi-mcp-server \
  211. --api-base-url https://api.example.com \
  212. --spec-inline '{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0.0"}, "paths": {}}'
  213. # Using environment variable
  214. export OPENAPI_SPEC_INLINE='{"openapi": "3.0.0", ...}'
  215. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com
  216. ```
  217. ### Supported Formats
  218. All loading methods support both JSON and YAML formats. The server automatically detects the format and parses accordingly.
  219. ### Docker and Container Usage
  220. For containerized deployments, you can mount OpenAPI specs or use stdin:
  221. ```bash
  222. # Mount local file
  223. docker run -v /path/to/spec:/app/spec.json your-mcp-server \
  224. --api-base-url https://api.example.com \
  225. --openapi-spec /app/spec.json
  226. # Use stdin with docker
  227. cat openapi.json | docker run -i your-mcp-server \
  228. --api-base-url https://api.example.com \
  229. --spec-from-stdin
  230. ```
  231. ### Error Handling
  232. The server provides detailed error messages for spec loading failures:
  233. - **URL loading**: HTTP status codes and network errors (a `401`/`403` from an authenticated spec URL usually means the headers or `--spec-auth` mode need adjusting)
  234. - **File loading**: File system errors (not found, permissions, etc.)
  235. - **Stdin loading**: Empty input or read errors
  236. - **Inline loading**: Missing content errors
  237. - **Parsing errors**: Detailed JSON/YAML syntax error messages
  238. ### Validation
  239. Only one specification source can be used at a time. The server will validate that exactly one of the following is provided:
  240. - `--openapi-spec` (URL or file path)
  241. - `--spec-from-stdin`
  242. - `--spec-inline`
  243. If multiple sources are specified, the server will exit with an error message.
  244. ## Tool Loading & Filtering Options
  245. Based on the Stainless article "What We Learned Converting Complex OpenAPI Specs to MCP Servers" (https://www.stainless.com/blog/what-we-learned-converting-complex-openapi-specs-to-mcp-servers), the following flags were added to control which API endpoints (tools) are loaded:
  246. - `--tools <all|dynamic|explicit>`: Choose tool loading mode:
  247. - `all` (default): Load all tools from the OpenAPI spec, applying any specified filters
  248. - `dynamic`: Load only dynamic meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`). `--exclude-tag` still applies to dynamic endpoint discovery and invocation.
  249. - `explicit`: Load only tools explicitly listed in `--tool` options, ignoring include filters. `--exclude-tag` still applies as a deny filter.
  250. - `--tool <toolId>`: Import only specified tool IDs or names. Can be used multiple times. In `all` mode, this bypasses `--tag`, `--resource`, and `--operation`, but not `--exclude-tag`.
  251. - `--tag <tag>`: Import only tools with the specified OpenAPI tag. Can be used multiple times.
  252. - `--exclude-tag <tag>`: Exclude tools with the specified OpenAPI tag. Can be used multiple times. Excluded tags take precedence over `--tool`.
  253. - `--resource <resource>`: Import only tools under the specified resource path prefixes. Can be used multiple times.
  254. - `--operation <method>`: Import only tools for the specified HTTP methods (get, post, etc). Can be used multiple times.
  255. Tag filters are tool-surface controls, not authorization. Keep protecting sensitive endpoints with the upstream API's auth model. Untagged endpoints are not affected by `--exclude-tag`.
  256. **Examples:**
  257. ```bash
  258. # Load only dynamic meta-tools
  259. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools dynamic
  260. # Load only explicitly specified tools (ignores other filters)
  261. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tools explicit --tool GET::users --tool POST::users
  262. # Load only the GET /users endpoint tool (using all mode with filtering)
  263. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tool GET-users
  264. # Load tools tagged with "user" under the "/users" resource
  265. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --tag user --resource users
  266. # Exclude admin and internal endpoints from any tool loading mode
  267. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --exclude-tag admin --exclude-tag internal
  268. # Load only POST operations
  269. npx @ivotoby/openapi-mcp-server --api-base-url https://api.example.com --openapi-spec https://api.example.com/openapi.json --operation post
  270. ```
  271. ## Server Instructions
  272. The MCP protocol lets a server describe how it is meant to be used: the text travels in the `initialize` result, and a client may add it to the system prompt of the model. It's the place for what an OpenAPI description can't say, such as what has to be called before what.
  273. ```typescript
  274. const config = {
  275. // …
  276. instructions: "Pages are created unapproved: approve the version once you are done.",
  277. }
  278. ```
  279. The same text can be given to the CLI with `--instructions` or with the `SERVER_INSTRUCTIONS` environment variable. Keep it short: it is handed over at every session, and it takes room in the context of the model.
  280. ## Prompts and Resources
  281. In addition to exposing OpenAPI endpoints as **tools**, this server can expose **prompts** (reusable templates) and **resources** (static content) via the MCP protocol.
  282. ### What Are Prompts and Resources?
  283. | Feature | Purpose | Use Case |
  284. | ------------- | --------------------------------------------- | --------------------------- |
  285. | **Tools** | API endpoints for the AI to execute | Making API calls |
  286. | **Prompts** | Templated messages with argument substitution | Reusable workflow templates |
  287. | **Resources** | Read-only content for context | API documentation, schemas |
  288. ### Loading Prompts
  289. Prompts can be loaded from files, URLs, or inline JSON:
  290. ```bash
  291. # Load from local file
  292. npx @ivotoby/openapi-mcp-server \
  293. --api-base-url https://api.example.com \
  294. --openapi-spec https://api.example.com/openapi.json \
  295. --prompts ./prompts.json
  296. # Load from URL
  297. npx @ivotoby/openapi-mcp-server \
  298. --api-base-url https://api.example.com \
  299. --openapi-spec https://api.example.com/openapi.json \
  300. --prompts https://example.com/mcp/prompts.json
  301. # Inline JSON
  302. npx @ivotoby/openapi-mcp-server \
  303. --api-base-url https://api.example.com \
  304. --openapi-spec https://api.example.com/openapi.json \
  305. --prompts-inline '[{"name":"greet","title":"Greeting","template":"Hello {{name}}!"}]'
  306. ```
  307. **Prompts File Format (JSON):**
  308. ```json
  309. [
  310. {
  311. "name": "api_request",
  312. "title": "API Request Helper",
  313. "description": "Helps generate API request templates",
  314. "arguments": [
  315. { "name": "endpoint", "description": "API endpoint path", "required": true },
  316. { "name": "method", "description": "HTTP method", "required": false }
  317. ],
  318. "template": "Create a {{method}} request to {{endpoint}} with proper parameters."
  319. }
  320. ]
  321. ```
  322. ### Loading Resources
  323. Resources can be loaded from files, URLs, or inline JSON:
  324. ```bash
  325. # Load from local file
  326. npx @ivotoby/openapi-mcp-server \
  327. --api-base-url https://api.example.com \
  328. --openapi-spec https://api.example.com/openapi.json \
  329. --mcp-resources ./resources.json
  330. # Load from URL
  331. npx @ivotoby/openapi-mcp-server \
  332. --api-base-url https://api.example.com \
  333. --openapi-spec https://api.example.com/openapi.json \
  334. --mcp-resources https://example.com/mcp/resources.json
  335. # Inline JSON
  336. npx @ivotoby/openapi-mcp-server \
  337. --api-base-url https://api.example.com \
  338. --openapi-spec https://api.example.com/openapi.json \
  339. --mcp-resources-inline '[{"uri":"docs://readme","name":"readme","text":"# Welcome"}]'
  340. ```
  341. **Resources File Format (JSON):**
  342. ```json
  343. [
  344. {
  345. "uri": "docs://api/overview",
  346. "name": "api-overview",
  347. "title": "API Overview",
  348. "description": "Overview of the API",
  349. "mimeType": "text/markdown",
  350. "text": "# API Overview\n\nThis API provides..."
  351. }
  352. ]
  353. ```
  354. ### Combining Tools, Prompts, and Resources
  355. ```bash
  356. npx @ivotoby/openapi-mcp-server \
  357. --api-base-url https://api.example.com \
  358. --openapi-spec https://api.example.com/openapi.json \
  359. --prompts ./prompts.json \
  360. --mcp-resources ./resources.json \
  361. --transport http \
  362. --port 3000
  363. ```
  364. With this configuration, the server advertises capabilities for all three:
  365. ```json
  366. {
  367. "capabilities": {
  368. "tools": { "list": true, "execute": true },
  369. "prompts": {},
  370. "resources": {}
  371. }
  372. }
  373. ```
  374. ## Transport Types
  375. ### Stdio Transport (Default)
  376. The stdio transport is designed for direct integration with AI systems like Claude Desktop that manage MCP connections through standard input/output. This is the simplest setup and requires no network configuration.
  377. **When to use**: When integrating with Claude Desktop or other systems that support stdio-based MCP communication.
  378. ### Streamable HTTP Transport
  379. The HTTP transport allows the MCP server to be accessed over HTTP, enabling web applications and other HTTP-capable clients to interact with the MCP protocol. It supports session management, streaming responses, and standard HTTP methods.
  380. **Key features**:
  381. - Session management with Mcp-Session-Id header
  382. - HTTP responses for `initialize` and `tools/list` requests are sent synchronously on the POST.
  383. - Other server-to-client messages (e.g., `tools/execute` results, notifications) are streamed over a GET connection using Server-Sent Events (SSE).
  384. - Support for POST/GET/DELETE methods
  385. **When to use**: When you need to expose the MCP server to web clients or systems that communicate over HTTP rather than stdio.
  386. ### Health Check Endpoint
  387. When using HTTP transport, a health check endpoint is available at `/health` for monitoring and service discovery:
  388. ```bash
  389. # Check server health
  390. curl http://localhost:3000/health
  391. # Response:
  392. # {
  393. # "status": "healthy",
  394. # "activeSessions": 2,
  395. # "uptime": 3600
  396. # }
  397. ```
  398. **Health Response Fields:**
  399. - `status`: Always returns "healthy" when server is running
  400. - `activeSessions`: Number of active MCP sessions
  401. - `uptime`: Server uptime in seconds
  402. **Key Features:**
  403. - No authentication required
  404. - Works with any HTTP method (GET, POST, etc.)
  405. - Ideal for load balancers, Kubernetes probes, and monitoring systems
  406. **Integration Examples:**
  407. ```yaml
  408. # Kubernetes liveness probe
  409. livenessProbe:
  410. httpGet:
  411. path: /health
  412. port: 3000
  413. initialDelaySeconds: 3
  414. periodSeconds: 10
  415. # Docker healthcheck
  416. HEALTHCHECK --interval=30s --timeout=3s \
  417. CMD curl -f http://localhost:3000/health || exit 1
  418. ```
  419. ## Security Considerations
  420. - The HTTP transport validates Origin headers to prevent DNS rebinding attacks
  421. - By default, HTTP transport only binds to localhost (127.0.0.1)
  422. - If exposing to other hosts, consider implementing additional authentication
  423. - Auth headers are only sent to a spec URL on the API's origin by default, and never across a cross-origin redirect; use `--spec-auth always` only for spec hosts you trust with your credentials
  424. ## Debugging
  425. To see debug logs:
  426. 1. When using stdio transport with Claude Desktop:
  427. - Logs appear in the Claude Desktop logs
  428. 2. When using HTTP transport:
  429. ```bash
  430. npx @ivotoby/openapi-mcp-server --transport http &2>debug.log
  431. ```
  432. ---
  433. # Library Usage
  434. This section is for developers who want to use this package as a library to create custom MCP servers.
  435. ## 🚀 Using as a Library
  436. Create dedicated MCP servers for specific APIs by importing and configuring the `OpenAPIServer` class. This approach is ideal for:
  437. - **Custom Authentication**: Implement complex authentication patterns with the `AuthProvider` interface
  438. - **API-Specific Optimizations**: Filter endpoints, customize error handling, and optimize for specific use cases
  439. - **Distribution**: Package your server as a standalone npm module for easy sharing
  440. - **Integration**: Embed the server in larger applications or add custom middleware
  441. ### Basic Library Usage
  442. ```typescript
  443. import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
  444. import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
  445. const config = {
  446. name: "my-api-server",
  447. version: "1.0.0",
  448. apiBaseUrl: "https://api.example.com",
  449. openApiSpec: "https://api.example.com/openapi.json",
  450. specInputMethod: "url" as const,
  451. headers: {
  452. Authorization: "Bearer your-token",
  453. "X-API-Key": "your-api-key",
  454. },
  455. transportType: "stdio" as const,
  456. toolsMode: "all" as const, // Options: "all", "dynamic", "explicit"
  457. }
  458. const server = new OpenAPIServer(config)
  459. const transport = new StdioServerTransport()
  460. await server.start(transport)
  461. ```
  462. ### Tool Loading Modes
  463. The `toolsMode` configuration option controls which tools are loaded from your OpenAPI specification:
  464. ```typescript
  465. // Load all tools from the spec (default)
  466. const config = {
  467. // ... other config
  468. toolsMode: "all" as const,
  469. // Optional: Apply filters to control which tools are loaded
  470. includeTools: ["GET::users", "POST::users"], // Only these tools
  471. includeTags: ["public"], // Only tools with these tags
  472. excludeTags: ["admin", "internal"], // Never expose tools with these tags
  473. includeResources: ["users"], // Only tools under these resources
  474. includeOperations: ["get", "post"], // Only these HTTP methods
  475. }
  476. // Load only dynamic meta-tools for API exploration
  477. const config = {
  478. // ... other config
  479. toolsMode: "dynamic" as const,
  480. // Provides: list-api-endpoints, get-api-endpoint-schema, invoke-api-endpoint
  481. // excludeTags still hides matching operations from discovery and invocation
  482. }
  483. // Load only explicitly specified tools (include filters are ignored)
  484. const config = {
  485. // ... other config
  486. toolsMode: "explicit" as const,
  487. includeTools: ["GET::users", "POST::users"], // Only these exact tools
  488. excludeTags: ["admin"], // Still applied as a deny filter
  489. // includeTags, includeResources, includeOperations are ignored in explicit mode
  490. }
  491. ```
  492. Tool names are unique per server. If two operations reduce to the same name (e.g. no `operationId` and summaries that only differ in non-ASCII characters), the first one in spec order keeps the name and later ones get a short suffix derived from their method and path (e.g. `ticket` and `ticket-e181`). Because which operation keeps the bare name depends on spec order, prefer tool IDs in `includeTools` when names collide (e.g. `POST::t__consume` for `POST /t/consume`; path segments are joined with `__`).
  493. ### Configuring Prompts and Resources
  494. Expose reusable prompts and static resources alongside your API tools:
  495. ```typescript
  496. import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
  497. const config = {
  498. name: "my-api-server",
  499. version: "1.0.0",
  500. apiBaseUrl: "https://api.example.com",
  501. openApiSpec: "https://api.example.com/openapi.json",
  502. specInputMethod: "url" as const,
  503. transportType: "stdio" as const,
  504. toolsMode: "all" as const,
  505. // Define prompts with argument templates
  506. prompts: [
  507. {
  508. name: "api_request",
  509. title: "API Request Helper",
  510. description: "Helps generate API request templates",
  511. arguments: [
  512. { name: "endpoint", description: "API endpoint path", required: true },
  513. { name: "method", description: "HTTP method", required: false },
  514. ],
  515. template: "Create a {{method}} request to {{endpoint}} with proper parameters.",
  516. },
  517. ],
  518. // Define resources with static content
  519. resources: [
  520. {
  521. uri: "docs://api/overview",
  522. name: "api-overview",
  523. title: "API Overview",
  524. description: "Overview of the API capabilities",
  525. mimeType: "text/markdown",
  526. text: "# API Overview\n\nThis API provides...",
  527. },
  528. ],
  529. }
  530. const server = new OpenAPIServer(config)
  531. ```
  532. ### Adding Extra Custom Tools
  533. You can expose a few hand-written MCP tools alongside the tools generated from your OpenAPI spec:
  534. ```typescript
  535. import { OpenAPIServer } from "@ivotoby/openapi-mcp-server"
  536. const extraTools = [
  537. {
  538. id: "add",
  539. tool: {
  540. name: "add",
  541. description: "Add two numbers",
  542. inputSchema: {
  543. type: "object",
  544. properties: {
  545. a: { type: "number" },
  546. b: { type: "number" },
  547. },
  548. required: ["a", "b"],
  549. },
  550. },
  551. handler: async (args) => {
  552. const a = Number(args.a)
  553. const b = Number(args.b)
  554. const result = a + b
  555. return {
  556. content: [{ type: "text", text: JSON.stringify({ result }) }],
  557. structuredContent: { result },
  558. }
  559. },
  560. },
  561. ]
  562. const server = new OpenAPIServer({
  563. name: "my-api-server",
  564. version: "1.0.0",
  565. apiBaseUrl: "https://api.example.com",
  566. openApiSpec: "https://api.example.com/openapi.json",
  567. specInputMethod: "url",
  568. transportType: "stdio",
  569. toolsMode: "all",
  570. extraTools,
  571. })
  572. ```
  573. Notes:
  574. - `extraTools` is library-only in this first version; there is no CLI format for function handlers
  575. - extra tool IDs and MCP tool names must be unique across both custom and OpenAPI-generated tools
  576. - extra tool handlers should return a normal MCP `tools/call` result object
  577. #### Dynamic Prompt and Resource Management
  578. You can also add prompts and resources dynamically after server creation:
  579. ```typescript
  580. const server = new OpenAPIServer(config)
  581. // Add prompts dynamically
  582. const promptsManager = server.getPromptsManager()
  583. if (promptsManager) {
  584. promptsManager.addPrompt({
  585. name: "debug_error",
  586. title: "Error Debugger",
  587. template: "Debug this API error: {{error_message}}",
  588. })
  589. }
  590. // Add resources dynamically
  591. const resourcesManager = server.getResourcesManager()
  592. if (resourcesManager) {
  593. resourcesManager.addResource({
  594. uri: "docs://changelog",
  595. name: "changelog",
  596. title: "API Changelog",
  597. mimeType: "text/markdown",
  598. text: "# Changelog\n\n## v1.0.0\n- Initial release",
  599. })
  600. }
  601. ```
  602. #### Prompt Definition Format
  603. ```typescript
  604. interface PromptDefinition {
  605. name: string // Unique identifier
  606. title?: string // Human-readable display title
  607. description?: string // Description of the prompt
  608. arguments?: {
  609. // Template arguments
  610. name: string
  611. description?: string
  612. required?: boolean
  613. }[]
  614. template: string // Template with {{argName}} placeholders
  615. }
  616. ```
  617. #### Resource Definition Format
  618. ```typescript
  619. interface ResourceDefinition {
  620. uri: string // Unique URI identifier
  621. name: string // Resource name
  622. title?: string // Human-readable display title
  623. description?: string // Description of the resource
  624. mimeType?: string // Content MIME type
  625. text?: string // Static text content
  626. blob?: string // Static binary content (base64)
  627. contentProvider?: () => Promise<string | { blob: string }> // Dynamic content
  628. }
  629. ```
  630. ### Advanced Authentication with AuthProvider
  631. For APIs with token expiration, refresh requirements, or complex authentication:
  632. ```typescript
  633. import { OpenAPIServer, AuthProvider } from "@ivotoby/openapi-mcp-server"
  634. import { AxiosError } from "axios"
  635. class MyAuthProvider implements AuthProvider {
  636. async getAuthHeaders(): Promise<Record<string, string>> {
  637. // Called before each request - return fresh headers
  638. if (this.isTokenExpired()) {
  639. await this.refreshToken()
  640. }
  641. return { Authorization: `Bearer ${this.token}` }
  642. }
  643. async handleAuthError(error: AxiosError): Promise<boolean> {
  644. // Called on 401/403 errors - return true to retry
  645. if (error.response?.status === 401) {
  646. await this.refreshToken()
  647. return true // Retry the request
  648. }
  649. return false
  650. }
  651. }
  652. const authProvider = new MyAuthProvider()
  653. const config = {
  654. // ... other config
  655. authProvider: authProvider, // Use AuthProvider instead of static headers
  656. }
  657. ```
  658. **📁 See the [examples/](./examples/) directory for complete, runnable examples including:**
  659. - Basic library usage with static authentication
  660. - AuthProvider implementations for different scenarios
  661. - Real-world Beatport API integration
  662. - Production-ready packaging patterns
  663. ## 🔐 Dynamic Authentication with AuthProvider
  664. The `AuthProvider` interface enables sophisticated authentication scenarios that static headers cannot handle:
  665. ### Key Features
  666. - **Dynamic Headers**: Fresh authentication headers for each request
  667. - **Token Expiration Handling**: Automatic detection and handling of expired tokens
  668. - **Authentication Error Recovery**: Retry logic for recoverable authentication failures
  669. - **Custom Error Messages**: Provide clear, actionable guidance to users
  670. ### AuthProvider Interface
  671. ```typescript
  672. interface AuthProvider {
  673. /**
  674. * Get authentication headers for the current request
  675. * Called before each API request to get fresh headers
  676. */
  677. getAuthHeaders(): Promise<Record<string, string>>
  678. /**
  679. * Handle authentication errors from API responses
  680. * Called when the API returns 401 or 403 errors
  681. * Return true to retry the request, false otherwise
  682. */
  683. handleAuthError(error: AxiosError): Promise<boolean>
  684. }
  685. ```
  686. ### Common Patterns
  687. #### Automatic Token Refresh
  688. ```typescript
  689. class RefreshableAuthProvider implements AuthProvider {
  690. async getAuthHeaders(): Promise<Record<string, string>> {
  691. if (this.isTokenExpired()) {
  692. await this.refreshToken()
  693. }
  694. return { Authorization: `Bearer ${this.accessToken}` }
  695. }
  696. async handleAuthError(error: AxiosError): Promise<boolean> {
  697. if (error.response?.status === 401) {
  698. await this.refreshToken()
  699. return true // Retry with fresh token
  700. }
  701. return false
  702. }
  703. }
  704. ```
  705. #### Manual Token Management (e.g., Beatport)
  706. ```typescript
  707. class ManualTokenAuthProvider implements AuthProvider {
  708. async getAuthHeaders(): Promise<Record<string, string>> {
  709. if (!this.token || this.isTokenExpired()) {
  710. throw new Error(
  711. "Token expired. Please get a new token from your browser:\n" +
  712. "1. Go to the API website and log in\n" +
  713. "2. Open browser dev tools (F12)\n" +
  714. "3. Copy the Authorization header from any API request\n" +
  715. "4. Update your token using updateToken()",
  716. )
  717. }
  718. return { Authorization: `Bearer ${this.token}` }
  719. }
  720. updateToken(token: string): void {
  721. this.token = token
  722. this.tokenExpiry = new Date(Date.now() + 3600000) // 1 hour
  723. }
  724. }
  725. ```
  726. #### API Key Authentication
  727. ```typescript
  728. class ApiKeyAuthProvider implements AuthProvider {
  729. constructor(private apiKey: string) {}
  730. async getAuthHeaders(): Promise<Record<string, string>> {
  731. return { "X-API-Key": this.apiKey }
  732. }
  733. async handleAuthError(error: AxiosError): Promise<boolean> {
  734. throw new Error("API key authentication failed. Please check your key.")
  735. }
  736. }
  737. ```
  738. **📖 For detailed AuthProvider documentation and examples, see [docs/auth-provider-guide.md](./docs/auth-provider-guide.md)**
  739. ### OpenAPI Schema Processing
  740. #### Reference Resolution
  741. This MCP server implements robust OpenAPI reference (`$ref`) resolution to ensure accurate representation of API schemas:
  742. - **Parameter References**: Fully resolves `$ref` pointers to parameter components in the OpenAPI spec
  743. - **Schema References**: Handles nested schema references within parameters and request bodies
  744. - **Recursive References**: Prevents infinite loops by detecting and handling circular references
  745. - **Nested Properties**: Preserves complex nested object and array structures with all their attributes
  746. ### Input Schema Composition
  747. The server intelligently merges parameters and request bodies into a unified input schema for each tool:
  748. - **Parameters + Request Body Merging**: Combines path, query, and body parameters into a single schema
  749. - **Collision Handling**: Resolves naming conflicts by prefixing body properties that conflict with parameter names
  750. - **Type Preservation**: Maintains the original type information for all schema elements
  751. - **Metadata Retention**: Preserves descriptions, formats, defaults, enums, and other schema attributes
  752. ### Complex Schema Support
  753. The MCP server handles various OpenAPI schema complexities:
  754. - **Primitive Type Bodies**: Exposes non-object request bodies as a "body" property; its value is sent as the request body itself (not wrapped in an object)
  755. - **Object Bodies**: Flattens object properties into the tool's input schema
  756. - **Array Bodies**: Properly handles array schemas with their nested item definitions
  757. - **Required Properties**: Tracks and preserves which parameters and properties are required
  758. ### Binary Request and Response Bodies
  759. - **Binary uploads**: Operations whose request body is binary (e.g. `application/octet-stream`, `image/png`, or any `type: string, format: binary` schema) get a `body` argument that takes **base64** (a `data:<type>;base64,...` URL is also accepted). The bytes are decoded and sent raw with the declared `Content-Type`.
  760. - **Binary responses**: Responses are read as raw bytes and decoded by `Content-Type`:
  761. - JSON → parsed and returned as JSON text
  762. - Text types (`text/*`, XML, YAML, ...) → returned verbatim as `text` content
  763. - `image/*` → MCP `image` content
  764. - `audio/*` → MCP `audio` content
  765. - Anything else (PDF, ZIP, `application/octet-stream`, ...) → an embedded `resource` with a base64 `blob`
  766. - **Resource URIs** are `api-response://<request path>`: the upstream host, credentials and query string are never exposed to the MCP client.
  767. - **Dynamic mode**: pass non-object bodies as `params.body` (base64 for binary bodies) to `INVOKE-API-ENDPOINT`; `GET-API-ENDPOINT-SCHEMA` reports this as `bodyParameter`.
  768. - **Library usage**: `ApiClient.executeApiCall()` returns a `BinaryResponse` (`data: Buffer`, `mimeType`, `uri`) for binary responses.
  769. ---
  770. # Developer Information
  771. ## For Developers
  772. ### Development Tools
  773. - `npm run build` - Builds the TypeScript source
  774. - `npm run clean` - Removes build artifacts
  775. - `npm test` - Runs the Vitest test suite
  776. - `npm run typecheck` - Runs TypeScript type checking
  777. - `npm run lint` - Runs type-aware ESLint against `src/**/*.ts`
  778. - `npm run dev` - Watches source files and rebuilds on changes
  779. - `npm run inspect-watch` - Runs the inspector with auto-reload on changes
  780. ### Verification Before Pull Requests
  781. Run the full local verification suite before opening a PR:
  782. ```bash
  783. npm run build
  784. npm test
  785. npm run typecheck
  786. npm run lint
  787. ```
  788. `npm run build` refreshes `dist/` so CLI execution tests use current code. `npm run lint` is intentionally type-aware and should be clean for all source files.
  789. ### Development Workflow
  790. 1. Clone the repository
  791. 2. Install dependencies: `npm install`
  792. 3. Start the development environment: `npm run inspect-watch`
  793. 4. Make changes to the TypeScript files in `src/`
  794. 5. The server will automatically rebuild and restart
  795. ### Contributing
  796. 1. Fork the repository
  797. 2. Create a feature branch
  798. 3. Make your changes
  799. 4. Run build, tests, typecheck, and linting: `npm run build && npm test && npm run typecheck && npm run lint`
  800. 5. Submit a pull request
  801. **📖 For comprehensive developer documentation, see [docs/developer-guide.md](./docs/developer-guide.md)**
  802. ---
  803. # FAQ
  804. **Q: What is a "tool"?**
  805. A: A tool corresponds to a single API endpoint derived from your OpenAPI specification, exposed as an MCP resource.
  806. **Q: How can I use this package in my own project?**
  807. A: You can import the `OpenAPIServer` class and use it as a library in your Node.js application. This allows you to create dedicated MCP servers for specific APIs with custom authentication, filtering, and error handling. See the [examples/](./examples/) directory for complete implementations.
  808. **Q: What's the difference between using the CLI and using it as a library?**
  809. A: The CLI is great for quick setup and testing, while the library approach allows you to create dedicated packages for specific APIs, implement custom authentication with `AuthProvider`, add custom logic, and distribute your server as a standalone npm module.
  810. **Q: How do I handle APIs with expiring tokens?**
  811. A: Use the `AuthProvider` interface instead of static headers. AuthProvider allows you to implement dynamic authentication with token refresh, expiration handling, and custom error recovery. See the AuthProvider examples for different patterns.
  812. **Q: What is AuthProvider and when should I use it?**
  813. A: `AuthProvider` is an interface for dynamic authentication that gets fresh headers before each request and handles authentication errors. Use it when your API has expiring tokens, requires token refresh, or needs complex authentication logic that static headers can't handle.
  814. **Q: How do I filter which tools are loaded?**
  815. A: Use the `--tool`, `--tag`, `--exclude-tag`, `--resource`, and `--operation` flags with `--tools all` (default), set `--tools dynamic` for meta-tools only, or use `--tools explicit` to load only tools specified with `--tool`. `--exclude-tag` is a deny filter and still applies in dynamic and explicit modes.
  816. **Q: When should I use dynamic mode?**
  817. A: Dynamic mode provides meta-tools (`list-api-endpoints`, `get-api-endpoint-schema`, `invoke-api-endpoint`) to inspect and interact with endpoints without preloading all operations, which is useful for large or changing APIs.
  818. **Q: What are prompts and resources?**
  819. A: **Prompts** are reusable message templates with argument placeholders (e.g., `{{name}}`) that can be retrieved via the MCP `prompts/get` method. **Resources** are static or dynamic content (text or binary) that can be read via the MCP `resources/read` method. Both are optional capabilities you can configure alongside tools.
  820. **Q: How do I expose prompts and resources from the CLI?**
  821. A: Use `--prompts <path|url>` for prompts and `--resources <path|url>` for resources. You can also use `--prompts-inline` and `--resources-inline` for inline JSON. See the "Prompts and Resources" section in the User Guide for details.
  822. **Q: How do I specify custom headers for API requests?**
  823. A: Use the `--headers` flag or `API_HEADERS` environment variable with `key:value` pairs separated by commas for CLI usage. For library usage, use the `headers` config option or implement an `AuthProvider` for dynamic headers.
  824. **Q: Which transport methods are supported?**
  825. A: The server supports stdio transport (default) for integration with AI systems and HTTP transport (with streaming via SSE) for web clients.
  826. **Q: How does the server handle complex OpenAPI schemas with references?**
  827. A: The server fully resolves `$ref` references in parameters and schemas, preserving nested structures, default values, and other attributes. See the "OpenAPI Schema Processing" section for details on reference resolution and schema composition.
  828. **Q: What happens when parameter names conflict with request body properties?**
  829. A: The server detects naming conflicts and automatically prefixes body property names with `body_` to avoid collisions, ensuring all properties are accessible.
  830. **Q: Can I package my MCP server for distribution?**
  831. A: Yes! When using the library approach, you can create a dedicated npm package for your API. See the Beatport example for a complete implementation that can be packaged and distributed as `npx your-api-mcp-server`.
  832. **Q: Where can I find development and contribution guidelines?**
  833. A: See the [Developer Guide](./docs/developer-guide.md) for comprehensive documentation on architecture, key concepts, development workflow, and contribution guidelines.
  834. ## License
  835. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.