FAQ - ivo-toby/mcp-openapi-server GitHub Wiki

Q: What is a "tool"?

A: A tool corresponds to a single API endpoint derived from your OpenAPI specification, exposed as an MCP resource.

Q: Are query parameters supported? How are they handled?

A: Yes! Query parameters are fully supported and automatically handled based on the HTTP method. For GET-like methods (GET, DELETE, HEAD, OPTIONS), query parameters are sent as URL query strings. For POST-like methods (POST, PUT, PATCH), they're included in the request body. Arrays are converted to comma-separated strings, and all parameter types are preserved. See the "Query Parameter Handling" section for detailed examples.

Q: How can I use this package in my own project?

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/ directory for complete implementations.

Q: What's the difference between using the CLI and using it as a library?

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.

Q: How do I handle APIs with expiring tokens?

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.

Q: What is AuthProvider and when should I use it?

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.

Q: How do I filter which tools are loaded?

A: Use the --tool, --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 (ignoring other filters).

Q: When should I use dynamic mode?

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.

Q: How do I specify custom headers for API requests?

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.

Q: Which transport methods are supported?

A: The server supports stdio transport (default) for integration with AI systems and HTTP transport (with streaming via SSE) for web clients.

Q: How does the server handle complex OpenAPI schemas with references?

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.

Q: What happens when parameter names conflict with request body properties?

A: The server detects naming conflicts and automatically prefixes body property names with body_ to avoid collisions, ensuring all properties are accessible.

Q: Can I package my MCP server for distribution?

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.

Q: Where can I find development and contribution guidelines?

A: See the Developer Guide for comprehensive documentation on architecture, key concepts, development workflow, and contribution guidelines.