mcphub/docs/openapi-schema-support.md

OpenAPI Schema Support in MCPHub

MCPHub now supports both OpenAPI specification URLs and complete JSON schemas for OpenAPI server configuration. This allows you to either reference an external OpenAPI specification file or embed the complete schema directly in your configuration.

Configuration Options

1. Using OpenAPI Specification URL (Traditional)

{
  "type": "openapi",
  "openapi": {
    "url": "https://api.example.com/openapi.json",
    "version": "3.1.0",
    "security": {
      "type": "apiKey",
      "apiKey": {
        "name": "X-API-Key",
        "in": "header",
        "value": "your-api-key"
      }
    }
  }
}

2. Using Complete JSON Schema (New)

{
  "type": "openapi",
  "openapi": {
    "schema": {
      "openapi": "3.1.0",
      "info": {
        "title": "My API",
        "version": "1.0.0"
      },
      "servers": [
        {
          "url": "https://api.example.com"
        }
      ],
      "paths": {
        "/users": {
          "get": {
            "operationId": "getUsers",
            "summary": "Get all users",
            "responses": {
              "200": {
                "description": "List of users"
              }
            }
          }
        }
      }
    },
    "version": "3.1.0",
    "security": {
      "type": "apiKey",
      "apiKey": {
        "name": "X-API-Key",
        "in": "header",
        "value": "your-api-key"
      }
    }
  }
}

Benefits of JSON Schema Support

1. Offline Development: No need for external URLs during development
2. Version Control: Schema changes can be tracked in your configuration
3. Security: No external dependencies or network calls required
4. Customization: Full control over the API specification
5. Testing: Easy to create test configurations with mock schemas

Frontend Form Support

The web interface now includes:

• Input Mode Selection: Choose between "Specification URL" or "JSON Schema"
• URL Input: Traditional URL input field for external specifications
• Schema Editor: Large text area with syntax highlighting for JSON schema input
• Validation: Client-side JSON validation before submission
• Help Text: Contextual help for schema format

API Validation

The backend validates that:

• At least one of url or schema is provided for OpenAPI servers
• JSON schemas are properly formatted when provided
• Security configurations are valid for both input modes
• All required OpenAPI fields are present

Migration Guide

From URL to Schema

If you want to convert an existing URL-based configuration to schema-based:

1. Download your OpenAPI specification from the URL
2. Copy the JSON content
3. Update your configuration to use the schema field instead of url
4. Paste the JSON content as the value of the schema field

Maintaining Both

You can include both url and schema in your configuration. The system will prioritize the schema field if both are present.

Examples

See the examples/openapi-schema-config.json file for complete configuration examples showing both URL and schema-based configurations.

Technical Implementation

• Backend: OpenAPI client supports both SwaggerParser.dereference() with URLs and direct schema objects
• Frontend: Dynamic form rendering based on selected input mode
• Validation: Enhanced validation logic in server controllers
• Type Safety: Updated TypeScript interfaces for both input modes

Header Passthrough Support

MCPHub supports passing through specific headers from tool call requests to upstream OpenAPI endpoints. This is useful for authentication tokens, API keys, and other request-specific headers.

Configuration

Add passthroughHeaders to your OpenAPI configuration:

{
  "type": "openapi",
  "openapi": {
    "url": "https://api.example.com/openapi.json",
    "version": "3.1.0",
    "passthroughHeaders": ["Authorization", "X-API-Key", "X-Custom-Header"],
    "security": {
      "type": "apiKey",
      "apiKey": {
        "name": "X-API-Key",
        "in": "header",
        "value": "your-api-key"
      }
    }
  }
}

How It Works

1. Configuration: List header names in the passthroughHeaders array
2. Tool Calls: When calling tools via HTTP API, include headers in the request
3. Passthrough: Only configured headers are forwarded to the upstream API
4. Case Insensitive: Header matching is case-insensitive for flexibility

Example Usage

# Call an OpenAPI tool with passthrough headers
curl -X POST "http://localhost:3000/api/tools/myapi/createUser" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-API-Key: your-api-key" \
  -H "X-Custom-Header: custom-value" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

In this example:

• If passthroughHeaders includes ["Authorization", "X-API-Key"]
• Only Authorization and X-API-Key headers will be forwarded
• X-Custom-Header will be ignored (not in passthrough list)
• Content-Type is handled by the OpenAPI operation definition

Security Considerations

• Whitelist Only: Only explicitly configured headers are passed through
• Sensitive Data: Be careful with headers containing sensitive information
• Validation: Upstream APIs should validate all received headers
• Logging: Headers may appear in logs - consider this for sensitive data

Security Considerations

When using JSON schemas:

• Ensure schemas are properly validated before use
• Be aware that large schemas increase configuration file size
• Consider using URL-based approach for frequently changing APIs
• Store sensitive information (like API keys) in environment variables, not in schemas

Troubleshooting

Common Issues

1. Invalid JSON: Ensure your schema is valid JSON format
2. Missing Required Fields: OpenAPI schemas must include openapi, info, and paths fields
3. Schema Size: Very large schemas may impact performance
4. Server Configuration: Ensure the servers field in your schema points to the correct endpoints

Validation Errors

The system provides detailed error messages for:

• Malformed JSON in schema field
• Missing required OpenAPI fields
• Invalid security configurations
• Network issues with URL-based configurations