AggregateProvider: silent duplicate tools, swallowed errors, unmasked child errors

[strawgate]

AggregateProvider (used by mount()) has three issues that affect server composition reliability:

1. Duplicate tool names across providers go undetected

When two providers contribute tools with the same name (e.g., mounting two sub-servers with the same namespace), _collect_list_results silently returns both. list_tools() shows duplicates and get_tool() returns whichever provider responds first. The parent server's on_duplicate setting is never checked across provider boundaries.

from fastmcp import FastMCP
import asyncio

async def main():
    main = FastMCP("Main", on_duplicate="error")
    sub1, sub2 = FastMCP("Sub1"), FastMCP("Sub2")

    @sub1.tool
    def greet(name: str) -> str: return f"Sub1: {name}"
    @sub2.tool
    def greet(name: str) -> str: return f"Sub2: {name}"

    main.mount(sub1, "ns")
    main.mount(sub2, "ns")  # No error!
    tools = await main.list_tools()
    print([t.name for t in tools])  # ['ns_greet', 'ns_greet']

asyncio.run(main())

2. Provider errors silently swallowed at DEBUG level

When a provider raises during list_tools() / list_resources() etc., _collect_list_results logs at DEBUG level (line 113) and skips the provider. All components from that provider silently disappear with no user-visible indication. This should be WARNING.

3. mask_error_details not propagated to mounted sub-servers

Setting mask_error_details=True on the parent server doesn't apply to errors from mounted sub-servers. Sensitive details (database passwords, internal paths, etc.) leak through child server error messages.

parent = FastMCP("parent", mask_error_details=True)
child = FastMCP("child")  # No masking

@child.tool
def secret_tool() -> str:
    raise ValueError("DATABASE_PASSWORD=hunter2")

parent.mount(child, "ns")
# Error response includes "DATABASE_PASSWORD=hunter2"

🤖 Generated with Claude Code

[marvin-context-protocol]

Claude finished @strawgate's task in 4m 41s —— View job

---

All three issues are confirmed and reproducible. Issues 2 and 3 are straightforward fixes; issue 1 requires a design decision.

• Investigate AggregateProvider and _collect_list_results
• Verify Issue 1: Duplicate tool names across providers
• Verify Issue 2: Provider errors swallowed at DEBUG level
• Verify Issue 3: mask_error_details not propagated to mounted sub-servers
• Provide recommendations and action plan

Recommendation

Issue 2 (log level) is a one-line fix. Issue 3 (mask_error_details propagation) is a focused fix in the parent server's error handling. Issue 1 (cross-provider duplicate detection) is a design question — the current architecture intentionally defers deduplication to protocol handlers via dedupe_with_versions, and on_duplicate only governs the LocalProvider. Adding cross-provider duplicate detection changes the contract of AggregateProvider and needs maintainer input on where it should live. Recommend splitting into separate PRs: one for issues 2+3, one for issue 1.

Findings

Issue 1 — Duplicate tool names across providers

Confirmed: mounting two sub-servers with the same namespace produces duplicate tool names in list_tools().

Tool names: ['ns_greet', 'ns_greet']

The on_duplicate setting only governs LocalProvider._add_component() (local_provider.py:189), which manages tools registered directly on a single server. AggregateProvider._collect_list_results() (aggregate.py:106-119) concatenates results from all providers without checking for name collisions. The protocol handler's dedupe_with_versions (mcp_operations.py:110) silently picks the highest version, which for unversioned duplicates means an arbitrary choice.

This is architecturally intentional — AggregateProvider was designed for "graceful degradation" with providers being independent. But it means on_duplicate="error" on a parent server is misleading: it only applies to tools registered directly on that server, not across mounted sub-servers.

Issue 2 — Provider errors logged at DEBUG

Confirmed: _collect_list_results at aggregate.py:113 logs provider errors at DEBUG level. With default logging, a failing provider's tools silently disappear:

DEBUG:fastmcp.server.providers.aggregate:Error during list_tools from provider FailingProvider(): Provider connection failed!

The same pattern exists in _get_highest_version_result at aggregate.py:135.

Issue 3 — mask_error_details not propagated

Confirmed: sensitive data leaks through child server errors. The flow:

1. Parent call_tool("ns_secret_tool") → finds FastMCPProviderTool
2. FastMCPProviderTool._run() → calls child.call_tool("secret_tool") (fastmcp_provider.py:144)
3. Child's call_tool catches the ValueError and wraps it as ToolError("Error calling tool 'secret_tool': DATABASE_PASSWORD=hunter2") — using the child's _mask_error_details=False (server.py:1183-1185)
4. ToolError extends FastMCPError, so the parent's handler at server.py:1163 re-raises it directly without applying the parent's masking

Parent mask_error_details: True
Child mask_error_details: False
Error message: Error calling tool 'secret_tool': DATABASE_PASSWORD=hunter2
Contains sensitive info: True

Verification

I installed the package and ran three verification scripts confirming all reported behaviors:

Issue 1:

main_server = FastMCP("Main", on_duplicate="error")
# ...mount two sub-servers with same namespace and same tool name...
tools = await main_server.list_tools()
# Result: ['ns_greet', 'ns_greet'] — no error raised

Issue 2:

# FailingProvider raises RuntimeError("Provider connection failed!")
# Only visible at DEBUG level:
# DEBUG:fastmcp.server.providers.aggregate:Error during list_tools from provider FailingProvider(): Provider connection failed!
# Tools from failing provider silently disappear

Issue 3:

parent = FastMCP("parent", mask_error_details=True)
child = FastMCP("child")  # No masking
# child tool raises ValueError("DATABASE_PASSWORD=hunter2")
# Error propagates unmasked: "Error calling tool 'secret_tool': DATABASE_PASSWORD=hunter2"

Detailed Action Plan

Fix 2: Change log level from DEBUG to WARNING (trivial)

File: src/fastmcp/server/providers/aggregate.py

Change line 113 and line 135 from logger.debug(...) to logger.warning(...):

# Line 113: _collect_list_results
logger.warning(
    f"Error during {operation} from provider "
    f"{self.providers[i]}: {result}"
)

# Line 135: _get_highest_version_result
logger.warning(
    f"Error during {operation} from provider "
    f"{self.providers[i]}: {result}"
)

Fix 3: Apply parent's mask_error_details to child errors

The fix belongs in the parent server's call_tool error handling path. When the child server raises a ToolError (or other FastMCPError) containing sensitive details, the parent should re-wrap it if mask_error_details=True.

File: src/fastmcp/server/server.py

At line 1163, where FastMCPError is caught and re-raised, add masking:

except FastMCPError as e:
    logger.exception(f"Error calling tool {name!r}")
    if self._mask_error_details and not isinstance(e, NotFoundError):
        raise ToolError(f"Error calling tool {name!r}") from e
    raise

The same pattern needs to be applied to read_resource and render_prompt error handlers where FastMCPError is caught and re-raised:

• read_resource (around lines 1280-1290 and 1320-1330)
• render_prompt (around lines 1429-1431)

Each should mask FastMCPError details when _mask_error_details=True, except for NotFoundError which doesn't contain sensitive info.

Fix 1: Cross-provider duplicate detection (requires design decision)

This is more nuanced. Options:

Option A — Detect duplicates in AggregateProvider._collect_list_results: Pass the parent's on_duplicate setting to AggregateProvider and check for name collisions after collecting all results. This adds coupling between AggregateProvider and the server's settings.

Option B — Detect duplicates in FastMCP.list_tools: After super().list_tools() returns, check for duplicate names and apply the on_duplicate policy. This keeps the detection at the server level where the policy lives.

Option C — Detect duplicates at mount time: When mount() is called, eagerly check if the new provider would create name collisions. This is harder since providers can be dynamic (tools may change after mount).

I'd lean toward Option B — it's the least invasive and keeps AggregateProvider generic. The check would go in FastMCP.list_tools() after line 582, before filtering. However, this is a design call for the maintainer.

Related Files

File	Relevance	Lines
src/fastmcp/server/providers/aggregate.py	Core file — _collect_list_results (issue 1+2) and _get_highest_version_result (issue 2)	106-119, 121-144
src/fastmcp/server/server.py	Error masking in call_tool (issue 3), on_duplicate setting (issue 1)	1162-1185, 292
src/fastmcp/server/providers/fastmcp_provider.py	FastMCPProviderTool._run() delegates to child call_tool	127-149
src/fastmcp/server/providers/local_provider/local_provider.py	on_duplicate enforcement (only for local components)	188-195
src/fastmcp/server/mixins/mcp_operations.py	Protocol handler dedup via dedupe_with_versions	110
src/fastmcp/exceptions.py	ToolError(FastMCPError) hierarchy	27
tests/client/client/test_error_handling.py	Existing mask_error_details tests (single server only)	—

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

DATABASE_PASSWORD=hunter2 well i guess i will have to stop using that password now