[BUG] RecursionError in resolve_schema_references() with self-referencing $ref schemas

Author: patelchaitanyCreated Apr 6, 2026Updated Jun 8, 2026
Labelsbug

Describe the bug A clear and concise description of what the bug is.

FastApiMCP crashes with RecursionError when the FastAPI app contains any Pydantic model with a self-referencing (recursive) type definition. The crash occurs during initialization in resolve_schema_references() and prevents the entire MCP server from starting - not just the affected route.

To Reproduce Steps to reproduce the behavior, including example code.

python

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Literal, Optional, Union
from fastapi_mcp import FastApiMCP

class ComparisonFilter(BaseModel):
    type: Literal["eq", "ne", "gt", "lt"]
    key: str
    value: str

class CompoundFilter(BaseModel):
    type: Literal["and", "or"]
    filters: List[Union[ComparisonFilter, "CompoundFilter"]]

CompoundFilter.model_rebuild()

class SearchRequest(BaseModel):
    query: str
    filters: Optional[Union[ComparisonFilter, CompoundFilter]] = None

app = FastAPI()

@app.post("/search")
async def search(request: SearchRequest):
    return {"status": "ok"}

This crashes:

mcp = FastApiMCP(app, name="test", description="test") mcp.mount()

System Info Please specify the relevant information of your work environment.

OS: macOS 26.4 Python: 3.12.12 fastapi-mcp: 0.4.0 fastapi: 0.128.7 pydantic: 2.12.5