External or non-local reference not supported

[jomo02]

Description

Hi, I'm trying to create a MCP server from my OpenAPI specification, but I'm getting the following errors:

fastmcp run server.py
[10/28/25 15:04:58] Failed to extract parameter 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Limit': Failed to resolve reference                    
                    'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Limit': External or non-local reference not supported:                             
                    https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Limit                                                                               
                    Failed to extract parameter 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Cursor': Failed to resolve reference                   
                    'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Cursor': External or non-local reference not supported:                            
                    https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Cursor                                                                              
                    Failed to extract parameter 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetKind': Failed to resolve reference                
                    'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetKind': External or non-local reference not supported:                         
                    https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetKind                                                                           
                    Failed to extract parameter 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetType': Failed to resolve reference                
                    'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetType': External or non-local reference not supported:                         
                    https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetType                                                                           
[10/28/25 15:04:58] ERROR    Failed to run: Failed to resolve reference                                                                                                                        cli.py:529
                             'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/schemas/GetAssetAdministrationShellDescriptorsResult': External or                   
                             non-local reference not supported:                                                                                                                                          
                             https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/schemas/GetAssetAdministrationShellDescriptorsResult     

I'm using the new OpenAPI parser, but it seems that this feature isn't supported yet?

Example Code

import yaml
import httpx
from fastmcp import FastMCP
import os

# Set this just in case, to use the new parser
os.environ["FASTMCP_EXPERIMENTAL_ENABLE_NEW_OPENAPI_PARSER"] = "true"

# Create an HTTP client for your API
client = httpx.AsyncClient(base_url="http://localhost:3000")

# Load your OpenAPI spec
with open("registry.yaml", "r") as f:
    openapi_spec = yaml.safe_load(f)

# Create the MCP server
mcp = FastMCP.from_openapi(openapi_spec=openapi_spec, client=client, name="AAS Registry Server")

if __name__ == "__main__":
    mcp.run()

registry.yaml

openapi: 3.0.3
info:
  title: DotAAS Part 2 | HTTP/REST | Asset Administration Shell Registry Service Specification
  description: >-
    The Full Profile of the Asset Administration Shell Registry Service Specification as part of the [Specification of the Asset Administration Shell: Part 2](http://industrialdigitaltwin.org/en/content-hub).  

    Publisher: Industrial Digital Twin Association (IDTA) 2023
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.0.1_SSP-001
servers:
  - url: "http://admin-shell.io:443/api/v3.0"
paths:
  /shell-descriptors:
    get:
      tags:
        - Asset Administration Shell Registry API
      summary: Returns all Asset Administration Shell Descriptors
      operationId: GetAllAssetAdministrationShellDescriptors
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellDescriptors/3/0
        - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellDescriptorsByAssetKind/3/0
        - https://admin-shell.io/aas/API/GetAllAssetAdministrationShellDescriptorsByAssetType/3/0
      parameters:
        - $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Limit"
        - $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/Cursor"
        - $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetKind"
        - $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/parameters/AssetType"
      responses:
        "200":
          description: Requested Asset Administration Shell Descriptors
          content:
            application/json:
              schema:
                $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/schemas/GetAssetAdministrationShellDescriptorsResult"
        default:
          $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.0.1#/components/responses/default"

Version Information

FastMCP version:                                                                                          2.13.0.1
MCP version:                                                                                                1.19.0
Python version:                                                                                            3.12.12
Platform:                                                                             macOS-26.0.1-arm64-arm-64bit
FastMCP root path: /Users/admin/projects/openapi-to-mcp/fastmcp/venv/lib/python3.12/site-packages

[jlowin]

Is the expectation in this case that the parser would load and inline the reference?

[jlowin]

This feels a little like it's going beyond what I want to maintain inside of fastmcp -- could you use a tool like https://github.com/RonnyPfannschmidt/prance to inline all references, then use fastmcp to parse it into an mcp server?

[jomo02]

Is the expectation in this case that the parser would load and inline the reference?

Yeah, something like this.

This feels a little like it's going beyond what I want to maintain inside of fastmcp -- could you use a tool like https://github.com/RonnyPfannschmidt/prance to inline all references, then use fastmcp to parse it into an mcp server?

It just worked in another project: https://github.com/harsha-iiiv/openapi-mcp-generator. That's why I thought external references are not so unusual. But I can also integrate the other tool in my pipeline.

Thanks for the quick reply!