fix: forward custom_route endpoints from mounted servers by voidborne-d · Pull Request #3462 · PrefectHQ/fastmcp

voidborne-d · 2026-03-11T07:09:49Z

Summary

Fixes #3457 — custom HTTP routes registered via @server.custom_route() on a child server are silently dropped when the child is mounted onto a parent, returning 404 instead of the expected response.

Root Cause

_get_additional_http_routes() in transport.py only returned self._additional_http_routes — routes from the current server. It never recursed into mounted providers to collect their custom routes.

When mount() creates a FastMCPProvider(child_server) and adds it to the parent's provider list, the child's HTTP routes are effectively invisible to http_app() which calls _get_additional_http_routes() to build the Starlette route table.

Fix

Updated _get_additional_http_routes() to:

Iterate through self.providers
Unwrap _WrappedProvider layers (added by namespace transforms)
Find FastMCPProvider instances
Recursively collect custom routes from their wrapped servers

This handles arbitrary nesting depth (server A mounts B which mounts C — A sees C's routes).

Tests

Added 4 tests in tests/server/mount/test_advanced.py:

test_mounted_server_custom_routes_forwarded — basic mount forwarding
test_mounted_server_custom_routes_with_namespace — namespaced mount
test_deeply_nested_custom_routes_forwarded — 3-level deep nesting
test_mounted_custom_routes_http_app_integration — end-to-end with TestClient reproducing the exact issue scenario

Reproducer (from issue)

import uvicorn
from fastmcp import FastMCP
from starlette.requests import Request
from starlette.responses import JSONResponse

mcp = FastMCP()
ready_mcp = FastMCP()

@ready_mcp.custom_route(path="/readyz", methods=["GET"])
async def readiness_check(request: Request) -> JSONResponse:
    return JSONResponse({"status": "ok"})

mcp.mount(ready_mcp)
app = mcp.http_app()
uvicorn.run(app=app, host="0.0.0.0", port=8000)

Before fix: curl http://localhost:8000/readyz → 404 Not Found
After fix: curl http://localhost:8000/readyz → {"status": "ok"}

When a child server with custom HTTP routes (registered via @server.custom_route()) is mounted onto a parent, the routes were silently dropped because _get_additional_http_routes() only returned self._additional_http_routes without recursing into mounted providers. This caused 404s for endpoints like /readyz health checks that worked in v2 but broke in v3 (regression). The fix updates _get_additional_http_routes() to traverse providers, unwrap _WrappedProvider layers (from namespace transforms), find FastMCPProvider instances, and recursively collect their server's custom routes. Fixes PrefectHQ#3457

marvin-context-protocol · 2026-03-11T07:12:28Z

Test Failure Analysis

Summary: The ty static type checker fails on tests/server/mount/test_advanced.py:190 because _get_additional_http_routes() is typed to return list[BaseRoute], and BaseRoute has no .path attribute — only the concrete Route subclass does.

Root Cause: The new test at line 190 (and existing one at line 86) directly accesses routes[0].path where routes is typed as list[BaseRoute]. Starlette's BaseRoute is an abstract base class without a path attribute; only the concrete Route class has it. The ty type checker correctly flags this as unresolved-attribute.

Suggested Solution: Two options, either works:

Option A — Narrow the type in the tests with isinstance assertions (minimal, test-only change):

from starlette.routing import Route

# line ~85-86
assert isinstance(routes[0], Route)
assert routes[0].path == "/test"

# line ~189-190
assert isinstance(routes[0], Route)
assert routes[0].path == "/health"

Option B — Change the type annotation in the implementation from list[BaseRoute] to list[Route] (more accurate, since only Route objects are ever stored):

src/fastmcp/server/server.py:258: self._additional_http_routes: list[Route] = []
src/fastmcp/server/mixins/transport.py:147,162: return type and variable annotation list[Route]

Option B is arguably cleaner because all items added to _additional_http_routes are Route(...) objects anyway, so the list[Route] type is more accurate. Note that line 148 in the test already guards with hasattr(route, "path") — that guard would become unnecessary with Option B, but is harmless to leave.

Detailed Analysis

Failing check:

ty check.................................................................[Failed]
- hook id: ty
- exit code: 1

  error[unresolved-attribute]: Object of type `BaseRoute` has no attribute `path`
     --> tests/server/mount/test_advanced.py:190:16
      |
  188 |         routes = parent._get_additional_http_routes()
  189 |         assert len(routes) == 1
  190 |         assert routes[0].path == "/health"
      |                ^^^^^^^^^^^^^^
  
  Found 1 diagnostic

Return type in question (src/fastmcp/server/mixins/transport.py:147):

def _get_additional_http_routes(self: FastMCP) -> list[BaseRoute]:

Actual routes stored (src/fastmcp/server/mixins/transport.py:135):

Route(
    path=path,
    endpoint=fn,
    methods=methods,
    ...
)

All items appended to _additional_http_routes are Route instances, so the return type list[BaseRoute] is overly broad. The BaseRoute abstract class lacks .path, hence ty's complaint.

Related Files

tests/server/mount/test_advanced.py:86,190 — the two test lines accessing .path without a type guard
src/fastmcp/server/mixins/transport.py:147,162 — _get_additional_http_routes return type annotation
src/fastmcp/server/server.py:258 — _additional_http_routes field type annotation

All items in _additional_http_routes are Route objects (created via Route(...) in custom_route()). Using list[Route] instead of list[BaseRoute] fixes the ty type checker failure where .path is accessed on BaseRoute which doesn't have that attribute. Removes unused BaseRoute imports from both server.py and transport.py.

marvin-context-protocol · 2026-03-11T12:09:57Z

Test Failure Analysis

(Updated to reflect the latest run — previous analyses are no longer relevant.)

Summary: The ruff check linter detected an import ordering violation in src/fastmcp/server/mixins/transport.py. Ruff auto-fixed it, but since prek's hook modified the file, CI treats this as a failure.

Root Cause: Three provider imports were added in the wrong position — before fastmcp.server.event_store and fastmcp.server.http imports. Ruff's isort rules require imports to follow alphabetical module order within the same package:

-from fastmcp.server.providers.base import Provider
-from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
-from fastmcp.server.providers.wrapped_provider import _WrappedProvider
 from fastmcp.server.event_store import EventStore
 from fastmcp.server.http import (
     StarletteWithLifespan,
     create_sse_app,
     create_streamable_http_app,
 )
+from fastmcp.server.providers.base import Provider
+from fastmcp.server.providers.fastmcp_provider import FastMCPProvider
+from fastmcp.server.providers.wrapped_provider import _WrappedProvider

Suggested Solution: Run prek run --all-files locally in your branch — it will auto-fix the import order in src/fastmcp/server/mixins/transport.py. Then commit the result.

uv run prek run --all-files
git add src/fastmcp/server/mixins/transport.py
git commit -m 'fix import order'

Detailed Analysis

Failing hook: ruff check (exit code 1, files modified by hook)

Log excerpt:

ruff check...............................................................[Failed]
- hook id: ruff-check
- exit code: 1
- files were modified by this hook

  Found 1 error (1 fixed, 0 remaining).

The hook auto-fixed the error, but prek sees the file modification and fails the run. The diff prek reported shows the provider imports need to come after event_store and http imports alphabetically.

Related Files

src/fastmcp/server/mixins/transport.py — the file with the import ordering issue (changed in this PR)

The previous commit narrowed _additional_http_routes from list[BaseRoute] to list[Route], which broke: - component_manager appending Mount objects (Mount is BaseRoute, not Route) - tests assigning list[BaseRoute] variables (generics are invariant) Revert to list[BaseRoute] and use isinstance(r, Route) guards in tests for type-safe .path access.

- Remove unused `Route` import from server.py - Fix import grouping in test_advanced.py (ruff check)

jlowin

Thanks! Some minor changes. Also it may be worth noting in the docstring that collisions will be resolved in favor of the parent server (I think). This is correct behavior, but worth noting.

jlowin · 2026-03-13T22:05:30Z

+            List of Starlette Route objects
        """
-        return list(self._additional_http_routes)
+        from fastmcp.server.providers.fastmcp_provider import FastMCPProvider


Please move imports to module root

Done — moved FastMCPProvider, _WrappedProvider, and Provider imports to module root in 5b44c8c.

jlowin · 2026-03-13T22:05:55Z

+
+        routes: list[BaseRoute] = list(self._additional_http_routes)
+
+        def _unwrap_provider(provider: Any) -> Any:


provider is typed as Provider here no? rather than Any. and the result is also Provider?

Good catch — updated to Provider for both the parameter and return type. Also added a docstring note about parent-wins collision resolution per your suggestion.

…sion note

@tool

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Jeremiah Lowin <jlowin@users.noreply.github.com> Co-authored-by: Marvin Context Protocol <41898282+Marvin Context Protocol@users.noreply.github.com> Co-authored-by: voidborne-d <voidborne-d@users.noreply.github.com> Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: d 🔹 <258577966+voidborne-d@users.noreply.github.com> Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Co-authored-by: nightcityblade <nightcityblade@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Bill Easton <strawgate@users.noreply.github.com> Co-authored-by: Sumanshu Nankana <sumanshunankana@gmail.com> Co-authored-by: Eric Robinson <ericrobinson@indeed.com> Co-authored-by: Martim Santos <martimfasantos@gmail.com> Co-authored-by: d 🔹 <liusway405@gmail.com> Co-authored-by: Matthieu B <66959271+mtthidoteu@users.noreply.github.com> Co-authored-by: Sascha Buehrle <47737812+saschabuehrle@users.noreply.github.com> Co-authored-by: Hakancan <142545736+hkc5@users.noreply.github.com> Co-authored-by: nightcityblade <jackchen@haloailabs.com> Co-authored-by: Matt Hallowell <17804673+mhallo@users.noreply.github.com> Co-authored-by: nate nowack <thrast36@gmail.com> Co-authored-by: Bill Easton <williamseaston@gmail.com> Co-authored-by: Marcus Shu <46469249+shulkx@users.noreply.github.com> Co-authored-by: Rushabh Doshi <radoshi@gmail.com> Co-authored-by: AIKAWA Shigechika <shige@aikawa.jp> Co-authored-by: Jeremy Simon <simonjer805@gmail.com> Co-authored-by: Miguel Miranda Dias <7780875+pandego@users.noreply.github.com> Co-authored-by: Anthony James Padavano <padavano.anthony@gmail.com> Co-authored-by: Mostafa Kamal <hiremostafa@gmail.com> Fix auto-close MRE script posting comment without closing (#3386) Fix WorkOS token scope verification bypass 🤖 Generated with Codex (#3407) Fix initialize McpError fallthrough 🤖 Generated with Codex (#3413) Fix transform arg collisions with passthrough params (#3431) Fix get_* returning None when latest version is disabled (#3439) Fix get_* returning None when latest version is disabled (#3421) Fix server lifespan overlap teardown (#3415) Fix $ref output schema object detection regression (#3420) resolved annotations (#3429) Fix async partial callables rejected by iscoroutinefunction (#3438) Fix async partial callables rejected by iscoroutinefunction (#3423) fix: add version to components (#3458) fix: use intent-based flag for OIDC scope patch in load_access_token (#3465) Fixes #3461 fix: normalize Google scope shorthands and surface valid_scopes (#3477) fix: resolve ty 0.0.23 type-checking errors and bump pin (#3481) fix: shield lifespan teardown from cancellation (#3480) fix: forward custom_route endpoints from mounted servers (#3462) fix updates _get_additional_http_routes() to traverse providers, Fixes #3457 fix: remove hardcoded version from CLI help text (#3456) fix: monty 0.0.8 compatibility, drop external_functions from constructor (#3468) fix: task test teardown hanging 5s per test (#3499) Closes #3498 fix: validate workspace path is a directory before cursor install (#3440) Fixes #3426 fix: handle re.error from malformed URI templates in build_regex (#3501) fix: reject empty/OIDC-only required_scopes in AzureProvider (#3503) fix: restrict $ref resolution to local refs only (SSRF/LFI) (#3502) fix warnings and timeouts (#3504) close upgrade check issue when build passes (#3505) Closes #3484 fix: URL-encode path params to prevent SSRF/path traversal (GHSA-vv7q-7jx5-f767) (#3507) fix: prevent path traversal in skill download (#3493) fix: prefer IdP-granted scopes over client-requested scopes in OAuthProxy (#3492) fix: remove unrelated transform and http.py changes from PR scope fix: remove forced follow_redirects from httpx_client_factory calls (#3496) fix: stop passing follow_redirects to httpx_client_factory fix: restore follow_redirects=True for custom httpx client factories Closes #3509 fix: CSRF double-submit cookie check in consent flow (#3519) fix: validate server names in install commands (#3522) fix: use raw strings for regex in pytest.raises match (#3523) fix: reject refresh tokens used as Bearer access tokens (#3524) fix: route ResourcesAsTools/PromptsAsTools through server middleware (#3495) fix: resolve Pyright "Module is not callable" on @tool, @resource, @prompt decorators (#3540) fix: filter warnings by message in KEY_PREFIX test (#3549) fix: suppress output schema for ToolResult subclass annotations (#3548) fix: increase sleep duration in proxy cache tests (#3567) fix: store absolute token expiry to prevent stale expires_in on reload (#3572) fix: preserve tool properties named 'title' during schema compression (#3582) Fix loopback redirect URI port matching per RFC 8252 §7.3 (#3589) Fix app tool routing: visibility check and middleware propagation (#3591) Fix query parameter serialization to respect OpenAPI explode/style settings (#3595) Fix dev apps form: union types, textarea support, JSON parsing (#3597) fix(google): replace deprecated /oauth2/v1/tokeninfo with /oauth2/v3/userinfo (#3603) fix: resolve EntraOBOToken dependency injection through MultiAuth (#3609) fix(docs): correct misleading stateless_http header (#3622) fix: filesystem provider import machinery (#3626) Closes #3625 (issues 2, 3, 6) fix: recover StdioTransport after subprocess exits (#3630) fix(server): preserve mounted tool task metadata (#3632) fix: scope deprecation warning filter to FastMCPDeprecationWarning (#3649) fix imports, add PrefabAppConfig (#3650) fix: resolve CurrentFastMCP/ctx.fastmcp to child server in mounted background tasks (#3651) Fix blocking docs issues: chart imports, Select API, Rx consistency (#3652) closed by default (#3657) Fix prompt caching middleware missing wrap/unwrap round-trip (#3666) fix: serialize object query params per OpenAPI style/explode rules (#3662) Fixes #2857 fix: HTTP request headers not accessible in background task workers (#3631) fix: restore HTTP headers in worker execution path for background tasks (#3681) fix: strip discriminator after dereferencing schemas (#3682) fix: remove stale ty:ignore directives for ty 0.0.26 (#3684) Fix docs gaps in app provider pages (#3690) fix: dev apps log panel UX improvements (#3698) fix dev server empty string args (#3700)

marvin-context-protocol bot added bug Something isn't working. Reports of errors, unexpected behavior, or broken functionality. http Related to HTTP transport, networking, or web server functionality. server Related to FastMCP server implementation or server-side functionality. labels Mar 11, 2026

voidborne-d and others added 2 commits March 11, 2026 12:18

fix: remove unused import and fix import grouping

695f496

- Remove unused `Route` import from server.py - Fix import grouping in test_advanced.py (ruff check)

jlowin requested changes Mar 13, 2026

View reviewed changes

voidborne-d and others added 2 commits March 14, 2026 00:06

Address review: move imports to module root, type Provider, add colli…

5b44c8c

…sion note

fix: sort imports in transport.py

5ab40af

jlowin merged commit 68e76fe into PrefectHQ:main Mar 14, 2026
4 of 6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: forward custom_route endpoints from mounted servers#3462

fix: forward custom_route endpoints from mounted servers#3462
jlowin merged 6 commits intoPrefectHQ:mainfrom
voidborne-d:fix/mount-custom-routes

voidborne-d commented Mar 11, 2026

Uh oh!

marvin-context-protocol bot commented Mar 11, 2026

Uh oh!

marvin-context-protocol bot commented Mar 11, 2026 •

edited

Loading

Uh oh!

jlowin left a comment

Uh oh!

jlowin Mar 13, 2026

Uh oh!

voidborne-d Mar 14, 2026

Uh oh!

jlowin Mar 13, 2026

Uh oh!

voidborne-d Mar 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		routes: list[BaseRoute] = list(self._additional_http_routes)

		def _unwrap_provider(provider: Any) -> Any:

Conversation

voidborne-d commented Mar 11, 2026

Summary

Root Cause

Fix

Tests

Reproducer (from issue)

Uh oh!

marvin-context-protocol bot commented Mar 11, 2026

Test Failure Analysis

Uh oh!

marvin-context-protocol bot commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Failure Analysis

Uh oh!

jlowin left a comment

Choose a reason for hiding this comment

Uh oh!

jlowin Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

voidborne-d Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

jlowin Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

voidborne-d Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marvin-context-protocol bot commented Mar 11, 2026 •

edited

Loading