Description

Issue Description

When using an OpenAPI specification that includes nested schemas with $ref, the following issues are encountered:

1. Validation Errors
Schemas with nested references like the following:

"/organizations/{organization_id}/events/": {
      "post": {
        "summary": "Create a new Event.",
        "parameters": [
          {
            "in": "path",
            "name": "organization_id",
            "description": "ID of the Organization that owns the Event. Example: 12345.",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
"responses": {
          "200": {
            "description": "Created new Event",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedEvent"
                }
              }
            }
          }
        },
....
components:
  schemas:
    CreatedEvent:
      type: object
      required:
        - created
        - changed
      properties:
        id:
          type: string
          description: Event ID
        name:
          $ref: "#/components/schemas/Name"
        ...

lead to validation errors such as:
ERROR:fastmcp.utilities.openapi:OpenAPI schema validation failed: 196 validation errors for OpenAPI
paths./organizations/{organization_id}/events/.post.responses.200.Response.content.application/json.schema.Reference.$ref
Field required [type=missing, input_value={'type': 'object', 'requi...d by one Organization.'}, input_type=JsonRef]
See: https://errors.pydantic.dev/2.11/v/missing
.......

2. Recursion Error
nested or circular references result in:

paths./organizations/{organization_id}/events/.post.responses.200.Response.content.application/json.schema.Schema.properties.category.Schema.properties.subcategories.Schema.items.Schema.properties.parent_category.Schema.properties.subcategories.Schema
Recursion error - cyclic reference detected [type=recursion_loop, input_value={'type': 'array', 'items'...own on some endpoints)'}, input_type=dict]

3.Missing Schema Reference Handling
If a $ref points to a schema that is not defined in the OpenAPI file, FastMCP currently exits with a generic error. Instead, it should return a clear and meaningful error message indicating the missing reference and its location.

4.Feature Request: Optional Output Schema Validation
Can we make output schema validation optional when creating tools from an OpenAPI specification? This would help in scenarios where strict validation is not required or where schemas are partially defined.

eventbrite.json

Example Code

import json
import httpx
from fastmcp import FastMCP

api_key = "your_api_key_here"
base_url = "https://www.eventbriteapi.com/v3"

headers = {
    "Authorization": f"Bearer {api_key}"
}



async def load_json(filepath):
    with open(filepath, "r", encoding="utf-8-sig") as file:
        data = json.load(file)
        return data

if __name__ == "__main__":
    spec = await load_json('eventbrite.json')
    client = httpx.AsyncClient(base_url=base_url, headers=headers)
    mcp = FastMCP.from_openapi(
        openapi_spec=spec,
        client=client,
        name="My API Server"
    )

Version Information

FastMCP version:                                                                              2.10.4
MCP version:                                                                                  1.11.0
Python version:                                                                               3.12

Additional Context

No response