> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI Integration

> Generate OpenAPI specifications from MCP tools for seamless integration with OpenWebUI and other systems

# OpenAPI Generation for OpenWebUI Integration

MCPHub now supports generating OpenAPI 3.0.3 specifications from MCP tools, enabling seamless integration with OpenWebUI and other OpenAPI-compatible systems without requiring MCPO as an intermediary proxy.

## Features

* ✅ **Automatic OpenAPI Generation**: Converts MCP tools to OpenAPI 3.0.3 specification
* ✅ **OpenWebUI Compatible**: Direct integration without MCPO proxy
* ✅ **Real-time Tool Discovery**: Dynamically includes tools from connected MCP servers
* ✅ **Dual Parameter Support**: Supports both GET (query params) and POST (JSON body) for tool execution
* ✅ **No Authentication Required**: OpenAPI endpoints are public for easy integration
* ✅ **Comprehensive Metadata**: Full OpenAPI specification with proper schemas and documentation

## API Endpoints

### OpenAPI Specification

<CodeGroup>
  ```bash GET /api/openapi.json theme={null}
  curl "http://localhost:3000/api/openapi.json"
  ```

  ```bash With Parameters theme={null}
  curl "http://localhost:3000/api/openapi.json?title=My MCP API&version=2.0.0"
  ```
</CodeGroup>

Generates and returns the complete OpenAPI 3.0.3 specification for all connected MCP tools.

**Query Parameters:**

<ParamField query="title" type="string" optional>
  Custom API title
</ParamField>

<ParamField query="description" type="string" optional>
  Custom API description
</ParamField>

<ParamField query="version" type="string" optional>
  Custom API version
</ParamField>

<ParamField query="serverUrl" type="string" optional>
  Custom server URL
</ParamField>

<ParamField query="includeDisabled" type="boolean" optional default="false">
  Include disabled tools
</ParamField>

<ParamField query="servers" type="string" optional>
  Comma-separated list of server names to include
</ParamField>

### Group/Server-Specific OpenAPI Specification

<CodeGroup>
  ```bash GET /api/:name/openapi.json theme={null}
  curl "http://localhost:3000/api/mygroup/openapi.json"
  ```

  ```bash With Parameters theme={null}
  curl "http://localhost:3000/api/myserver/openapi.json?title=My Server API&version=1.0.0"
  ```
</CodeGroup>

Generates and returns the OpenAPI 3.0.3 specification for a specific group or server. If a group with the given name exists, it returns the specification for all servers in that group. Otherwise, it treats the name as a server name and returns the specification for that server only.

**Path Parameters:**

<ParamField path="name" type="string" required>
  Group ID/name or server name
</ParamField>

**Query Parameters:**

Same as the main OpenAPI specification endpoint (title, description, version, serverUrl, includeDisabled).

### Available Servers

<CodeGroup>
  ```bash GET /api/openapi/servers theme={null}
  curl "http://localhost:3000/api/openapi/servers"
  ```
</CodeGroup>

Returns a list of connected MCP server names.

<ResponseExample>
  ```json Example Response theme={null}
  {
    "success": true,
    "data": ["amap", "playwright", "slack"]
  }
  ```
</ResponseExample>

### Tool Statistics

<CodeGroup>
  ```bash GET /api/openapi/stats theme={null}
  curl "http://localhost:3000/api/openapi/stats"
  ```
</CodeGroup>

Returns statistics about available tools and servers.

<ResponseExample>
  ```json Example Response theme={null}
  {
    "success": true,
    "data": {
      "totalServers": 3,
      "totalTools": 41,
      "serverBreakdown": [
        {"name": "amap", "toolCount": 12, "status": "connected"},
        {"name": "playwright", "toolCount": 21, "status": "connected"},
        {"name": "slack", "toolCount": 8, "status": "connected"}
      ]
    }
  }
  ```
</ResponseExample>

### Tool Execution

<CodeGroup>
  ```bash GET /api/tools/{serverName}/{toolName} theme={null}
  curl "http://localhost:3000/api/tools/amap/amap-maps_weather?city=Beijing"
  ```

  ```bash POST /api/tools/{serverName}/{toolName} theme={null}
  curl -X POST "http://localhost:3000/api/tools/playwright/playwright-browser_navigate" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'
  ```
</CodeGroup>

Execute MCP tools via OpenAPI-compatible endpoints.

**Path Parameters:**

<ParamField path="serverName" type="string" required>
  The name of the MCP server
</ParamField>

<ParamField path="toolName" type="string" required>
  The name of the tool to execute
</ParamField>

## OpenWebUI Integration

To integrate MCPHub with OpenWebUI:

<Steps>
  <Step title="Start MCPHub">
    Ensure MCPHub is running with your MCP servers configured
  </Step>

  <Step title="Get OpenAPI Specification">
    ```bash theme={null}
    curl http://localhost:3000/api/openapi.json > mcphub-api.json
    ```
  </Step>

  <Step title="Add to OpenWebUI">
    Import the OpenAPI specification file or point to the URL directly in OpenWebUI
  </Step>
</Steps>

### Configuration Example

In OpenWebUI, you can add MCPHub as an OpenAPI tool by using:

<CardGroup cols={2}>
  <Card title="OpenAPI URL" icon="link">
    `http://localhost:3000/api/openapi.json`
  </Card>

  <Card title="Base URL" icon="server">
    `http://localhost:3000/api`
  </Card>
</CardGroup>

## Generated OpenAPI Structure

The generated OpenAPI specification includes:

### Tool Conversion Logic

* **Simple tools** (≤10 primitive parameters) → GET endpoints with query parameters
* **Complex tools** (objects, arrays, or >10 parameters) → POST endpoints with JSON request body
* **All tools** include comprehensive response schemas and error handling

### Example Generated Operation

```yaml theme={null}
/tools/amap/amap-maps_weather:
  get:
    summary: "根据城市名称或者标准adcode查询指定城市的天气"
    operationId: "amap_amap-maps_weather"
    tags: ["amap"]
    parameters:
      - name: city
        in: query
        required: true
        description: "城市名称或者adcode"
        schema:
          type: string
    responses:
      '200':
        description: "Successful tool execution"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolResponse'
```

### Security

* The OpenAPI specification and tool execution endpoints are mounted **outside** the authenticated router (see `app.use(${BASE_PATH}/api, router)` versus the `app.get(${BASE_PATH}/api/openapi*)` and `app.get(${BASE_PATH}/api/tools/...)` registrations in `src/routes/index.ts`). They do not require a JWT, bearer key, OAuth token, or Better Auth session.
* For private deployments, gate these endpoints at your reverse proxy or only expose MCPHub on a trusted network.

## Benefits over MCPO

<CardGroup cols={2}>
  <Card title="Direct Integration" icon="plug">
    No need for intermediate proxy
  </Card>

  <Card title="Real-time Updates" icon="refresh">
    OpenAPI spec updates automatically as MCP servers connect/disconnect
  </Card>

  <Card title="Better Performance" icon="bolt">
    Direct tool execution without proxy overhead
  </Card>

  <Card title="Simplified Architecture" icon="layer-group">
    One less component to manage
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="OpenAPI spec shows no tools">
    Ensure MCP servers are connected. Check `/api/openapi/stats` for server status.
  </Accordion>

  <Accordion title="Tool execution fails">
    Verify the tool name and parameters match the OpenAPI specification. Check server logs for details.
  </Accordion>

  <Accordion title="OpenWebUI can't connect">
    Ensure MCPHub is accessible from OpenWebUI and the OpenAPI URL is correct.
  </Accordion>

  <Accordion title="Missing tools in specification">
    Check if tools are enabled in your MCP server configuration. Use `includeDisabled=true` to see all tools.
  </Accordion>
</AccordionGroup>