prefecthq--fastmcp/v3-notes/get-methods-consolidation.md

Consolidating Discovery Methods

This document captures the design decisions around component listing methods in FastMCP 3.0.

Problem

The server had parallel implementations for listing components:

• get_tools() / _list_tools()
• get_resources() / _list_resources()
• get_prompts() / _list_prompts()
• get_resource_templates() / _list_resource_templates()

These were nearly identical but with subtle differences in dedup keys, logging, and return types. The _list_* methods were internal and used by the MCP protocol handlers, while get_* methods were the public API.

Solution

The duplicate methods were consolidated into a single set of list_* methods. The old get_* plural methods and _list_* internal methods were both removed.

This happened in two phases:

1. Consolidation (Dec 2025): Merged get_* and _list_* into a single get_* method with an apply_middleware parameter.
2. Rename (Jan 2026): When FastMCP was refactored to inherit from Provider, the methods were renamed to list_* to align with the Provider interface. The apply_middleware parameter was renamed to run_middleware with a default of True.

async def list_tools(self, *, run_middleware: bool = True) -> Sequence[Tool]:
    """Canonical method for listing tools."""
    ...

Key Changes

Return Type: dict → list

The dict return type was removed because the key was redundant—components already have .name or .uri attributes.

# Before (v2.x)
tools = await server.get_tools()
tool = tools["my_tool"]

# After (v3.0)
tools = await server.list_tools()
tool = next(t for t in tools if t.name == "my_tool")

Middleware via Parameter

The run_middleware=True parameter (default) applies the middleware chain. This replaces the separate _list_*_middleware() methods.

Benefits

1. Single source of truth - One method, not two
2. Consistent behavior - Same dedup key, same visibility filtering
3. Clearer API - Public method with explicit middleware opt-in
4. Provider alignment - FastMCP.list_tools() overrides Provider.list_tools()
5. Less code - Deleted ~200 lines of duplicate implementation

Implementation Files

• src/fastmcp/server/server.py - Canonical list_* methods
• src/fastmcp/server/providers/ - Provider base class defines the interface