diff --git a/docs/my-website/docs/mcp.md b/docs/my-website/docs/mcp.md index fcbb31c07d3..822b3f5fabc 100644 --- a/docs/my-website/docs/mcp.md +++ b/docs/my-website/docs/mcp.md @@ -336,175 +336,9 @@ litellm_settings: ## Converting OpenAPI Specs to MCP Servers -LiteLLM can automatically convert OpenAPI specifications into MCP servers, allowing you to expose any REST API as MCP tools. This is useful when you have existing APIs with OpenAPI/Swagger documentation and want to make them available as MCP tools. +LiteLLM can convert OpenAPI specifications into MCP servers, exposing any REST API as MCP tools without writing custom server code. -**Benefits:** - -- **Rapid Integration**: Convert existing APIs to MCP tools without writing custom MCP server code -- **Automatic Tool Generation**: LiteLLM automatically generates MCP tools from your OpenAPI spec -- **Unified Interface**: Use the same MCP interface for both native MCP servers and OpenAPI-based APIs -- **Easy Testing**: Test and iterate on API integrations quickly - -**Configuration:** - -Add your OpenAPI-based MCP server to your `config.yaml`: - -```yaml title="config.yaml - OpenAPI to MCP" showLineNumbers -model_list: - - model_name: gpt-4o - litellm_params: - model: openai/gpt-4o - api_key: sk-xxxxxxx - -mcp_servers: - # OpenAPI Spec Example - Petstore API - petstore_mcp: - url: "https://petstore.swagger.io/v2" - spec_path: "/path/to/openapi.json" - auth_type: "none" - - # OpenAPI Spec with API Key Authentication - my_api_mcp: - url: "http://0.0.0.0:8090" - spec_path: "/path/to/openapi.json" - auth_type: "api_key" - auth_value: "your-api-key-here" - - # OpenAPI Spec with Bearer Token - secured_api_mcp: - url: "https://api.example.com" - spec_path: "/path/to/openapi.json" - auth_type: "bearer_token" - auth_value: "your-bearer-token" -``` - -**Configuration Parameters:** - -| Parameter | Required | Description | -|-----------|----------|-------------| -| `url` | Yes | The base URL of your API endpoint | -| `spec_path` | Yes | Path or URL to your OpenAPI specification file (JSON or YAML) | -| `auth_type` | No | Authentication type: `none`, `api_key`, `bearer_token`, `basic`, `authorization` | -| `auth_value` | No | Authentication value (required if `auth_type` is set) | -| `authorization_url` | No | For `auth_type: oauth2`. Optional override; if omitted LiteLLM auto-discovers it. | -| `token_url` | No | For `auth_type: oauth2`. Optional override; if omitted LiteLLM auto-discovers it. | -| `registration_url` | No | For `auth_type: oauth2`. Optional override; if omitted LiteLLM auto-discovers it. | -| `scopes` | No | For `auth_type: oauth2`. Optional override; if omitted LiteLLM uses the scopes advertised by the server. | -| `description` | No | Optional description for the MCP server | -| `allowed_tools` | No | List of specific tools to allow (see [MCP Tool Filtering](#mcp-tool-filtering)) | -| `disallowed_tools` | No | List of specific tools to block (see [MCP Tool Filtering](#mcp-tool-filtering)) | - -### Usage Example - -Once configured, you can use the OpenAPI-based MCP server just like any other MCP server: - - - - -```python title="Using OpenAPI-based MCP Server" showLineNumbers -from fastmcp import Client -import asyncio - -# Standard MCP configuration -config = { - "mcpServers": { - "petstore": { - "url": "http://localhost:4000/petstore_mcp/mcp", - "headers": { - "x-litellm-api-key": "Bearer sk-1234" - } - } - } -} - -# Create a client that connects to the server -client = Client(config) - -async def main(): - async with client: - # List available tools generated from OpenAPI spec - tools = await client.list_tools() - print(f"Available tools: {[tool.name for tool in tools]}") - - # Example: Get a pet by ID (from Petstore API) - response = await client.call_tool( - name="getpetbyid", - arguments={"petId": "1"} - ) - print(f"Response:\n{response}\n") - - # Example: Find pets by status - response = await client.call_tool( - name="findpetsbystatus", - arguments={"status": "available"} - ) - print(f"Response:\n{response}\n") - -if __name__ == "__main__": - asyncio.run(main()) -``` - - - - - -```json title="Cursor MCP Configuration for OpenAPI Server" showLineNumbers -{ - "mcpServers": { - "Petstore": { - "url": "http://localhost:4000/petstore_mcp/mcp", - "headers": { - "x-litellm-api-key": "Bearer $LITELLM_API_KEY" - } - } - } -} -``` - - - - - -```bash title="Using OpenAPI MCP Server with OpenAI" showLineNumbers -curl --location 'https://api.openai.com/v1/responses' \ ---header 'Content-Type: application/json' \ ---header "Authorization: Bearer $OPENAI_API_KEY" \ ---data '{ - "model": "gpt-4o", - "tools": [ - { - "type": "mcp", - "server_label": "petstore", - "server_url": "http://localhost:4000/petstore_mcp/mcp", - "require_approval": "never", - "headers": { - "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY" - } - } - ], - "input": "Find all available pets in the petstore", - "tool_choice": "required" -}' -``` - - - - -**How It Works** - -1. **Spec Loading**: LiteLLM loads your OpenAPI specification from the provided `spec_path` -2. **Tool Generation**: Each API endpoint in the spec becomes an MCP tool -3. **Parameter Mapping**: OpenAPI parameters are automatically mapped to MCP tool parameters -4. **Request Handling**: When a tool is called, LiteLLM converts the MCP request to the appropriate HTTP request -5. **Response Translation**: API responses are converted back to MCP format - -**OpenAPI Spec Requirements** - -Your OpenAPI specification should follow standard OpenAPI/Swagger conventions: -- **Supported versions**: OpenAPI 3.0.x, OpenAPI 3.1.x, Swagger 2.0 -- **Required fields**: `paths`, `info` sections should be properly defined -- **Operation IDs**: Each operation should have a unique `operationId` (this becomes the tool name) -- **Parameters**: Request parameters should be properly documented with types and descriptions +See the **[MCP from OpenAPI Specs guide](./mcp_openapi.md)** for full setup, usage examples, and how to override tool names and descriptions. ## MCP OAuth diff --git a/docs/my-website/docs/mcp_openapi.md b/docs/my-website/docs/mcp_openapi.md new file mode 100644 index 00000000000..0ac90dc12e9 --- /dev/null +++ b/docs/my-website/docs/mcp_openapi.md @@ -0,0 +1,232 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# MCP from OpenAPI Specs + +LiteLLM can automatically convert OpenAPI specifications into MCP servers, exposing any REST API as MCP tools without writing custom MCP server code. + +## Adding an OpenAPI MCP Server + +Add your OpenAPI-based MCP server in `config.yaml`: + +```yaml title="config.yaml" showLineNumbers +mcp_servers: + # OpenAPI Spec Example - Petstore API + petstore_mcp: + url: "https://petstore.swagger.io/v2" + spec_path: "/path/to/openapi.json" + auth_type: "none" + + # OpenAPI Spec with API Key Authentication + my_api_mcp: + url: "http://0.0.0.0:8090" + spec_path: "/path/to/openapi.json" + auth_type: "api_key" + auth_value: "your-api-key-here" + + # OpenAPI Spec with Bearer Token + secured_api_mcp: + url: "https://api.example.com" + spec_path: "/path/to/openapi.json" + auth_type: "bearer_token" + auth_value: "your-bearer-token" +``` + +**Configuration parameters:** + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `url` | Yes | Base URL of your API endpoint | +| `spec_path` | Yes | Path or URL to your OpenAPI spec file (JSON or YAML) | +| `auth_type` | No | `none`, `api_key`, `bearer_token`, `basic`, `authorization`, `oauth2` | +| `auth_value` | No | Auth value (required if `auth_type` is set) | +| `description` | No | Optional description for the MCP server | +| `allowed_tools` | No | List of specific tools to allow | +| `disallowed_tools` | No | List of specific tools to block | + +**Supported OpenAPI versions:** 3.0.x, 3.1.x, Swagger 2.0 + +Each operation's `operationId` becomes the MCP tool name, so make sure your spec has unique `operationId` values. + +## Using the Server + + + + +```python title="Using OpenAPI-based MCP Server" showLineNumbers +from fastmcp import Client +import asyncio + +config = { + "mcpServers": { + "petstore": { + "url": "http://localhost:4000/petstore_mcp/mcp", + "headers": { + "x-litellm-api-key": "Bearer sk-1234" + } + } + } +} + +client = Client(config) + +async def main(): + async with client: + tools = await client.list_tools() + print(f"Available tools: {[tool.name for tool in tools]}") + + response = await client.call_tool( + name="getpetbyid", + arguments={"petId": "1"} + ) + print(f"Response: {response}") + +if __name__ == "__main__": + asyncio.run(main()) +``` + + + + + +```json title="Cursor MCP Configuration" showLineNumbers +{ + "mcpServers": { + "Petstore": { + "url": "http://localhost:4000/petstore_mcp/mcp", + "headers": { + "x-litellm-api-key": "Bearer $LITELLM_API_KEY" + } + } + } +} +``` + + + + + +```bash title="Using OpenAPI MCP Server with OpenAI" showLineNumbers +curl --location 'https://api.openai.com/v1/responses' \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer $OPENAI_API_KEY" \ +--data '{ + "model": "gpt-4o", + "tools": [ + { + "type": "mcp", + "server_label": "petstore", + "server_url": "http://localhost:4000/petstore_mcp/mcp", + "require_approval": "never", + "headers": { + "x-litellm-api-key": "Bearer YOUR_LITELLM_API_KEY" + } + } + ], + "input": "Find all available pets in the petstore", + "tool_choice": "required" +}' +``` + + + + +## Overriding Tool Names and Descriptions + +By default, tool names and descriptions come directly from the `operationId` and description fields in your OpenAPI spec. You can override these per-server so MCP clients see friendlier names and clearer descriptions — without touching the upstream spec. + +This is useful when: +- The spec uses machine-generated `operationId` values like `getPetById_v2_deprecated` +- You want to simplify descriptions for your team +- You're exposing the same API to multiple audiences with different naming conventions + +### Via the UI + +When adding or editing an MCP server in the LiteLLM UI, each tool card in the **Tool Configuration** section has a pencil icon. Click it to open an inline edit panel: + +- **Display Name** — overrides the tool name shown to MCP clients +- **Description** — overrides the tool description shown to MCP clients + +A purple **Custom name** badge appears on any tool with an active override. Leave a field blank to keep the original value from the spec. + +### Via the API + +Pass `tool_name_to_display_name` and `tool_name_to_description` when creating or updating an MCP server: + +```bash title="Create server with tool overrides" showLineNumbers +curl -X POST http://localhost:4000/v1/mcp/server \ + -H "Authorization: Bearer $LITELLM_MASTER_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "petstore_mcp", + "url": "https://petstore.swagger.io/v2", + "spec_path": "/path/to/openapi.json", + "tool_name_to_display_name": { + "getPetById": "Get Pet", + "findPetsByStatus": "List Available Pets" + }, + "tool_name_to_description": { + "getPetById": "Look up a pet by its ID", + "findPetsByStatus": "Returns all pets that match the given status (available, pending, sold)" + } + }' +``` + +```bash title="Update overrides on an existing server" showLineNumbers +curl -X PUT http://localhost:4000/v1/mcp/server/{server_id} \ + -H "Authorization: Bearer $LITELLM_MASTER_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "tool_name_to_display_name": { + "getPetById": "Get Pet" + }, + "tool_name_to_description": { + "getPetById": "Look up a pet by its ID" + } + }' +``` + +### How It Works + +The key used in both maps is the **original tool name** from the spec (the `operationId`), not the prefixed name. LiteLLM strips the server prefix before looking up overrides. + +For example, if your server is named `petstore_mcp`, the tool is exposed as `petstore_mcp-getPetById`. The map key is still `getPetById`: + +```json +{ + "tool_name_to_display_name": { + "getPetById": "Get Pet" + } +} +``` + +After the override, MCP clients will see `"Get Pet"` instead of `"petstore_mcp-getPetById"`. + +### Example: Before and After + +Admin configures on the `petstore_mcp` server: +```json +{ + "tool_name_to_display_name": { + "getPetById": "Get Pet", + "findPetsByStatus": "List Available Pets" + }, + "tool_name_to_description": { + "getPetById": "Look up a pet by its ID", + "findPetsByStatus": "Returns all pets matching the given status" + } +} +``` + +MCP client calls `tools/list` and sees: + +``` +Tool: "Get Pet" +Description: "Look up a pet by its ID" + +Tool: "List Available Pets" +Description: "Returns all pets matching the given status" + +Tool: "petstore_mcp-addPet" ← no override, original name shown +Description: "Add a new pet to the store" +``` diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index f7487d24b12..8701ce0210c 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -608,6 +608,7 @@ const sidebars = { items: [ "mcp", "mcp_usage", + "mcp_openapi", "mcp_oauth", "mcp_public_internet", "mcp_semantic_filter",