Design: future of `dependencies` parameter on MCPServer

Context

PR #1877 removed the dependencies parameter from FastMCP (now MCPServer). After investigation, we're restoring it for now because removing it without a replacement breaks high-profile users and leaves a functionality gap. This issue tracks the design decision for what to do long-term.

What dependencies does

It's a list of pip/uv package names declared on the server instance:

mcp = MCPServer("Screenshot Demo", dependencies=["pyautogui", "Pillow"])

The only consumer is the mcp CLI — mcp dev and mcp install read server.dependencies via hasattr/getattr and convert them to uv run --with <pkg> flags when launching the server or writing Claude Desktop config. See https://github.com/modelcontextprotocol/python-sdk/blob/7ba4fb881d85406f44a5af8169fb7200fa7c8e49/src/mcp/cli/cli.py#L261-L262 and https://github.com/modelcontextprotocol/python-sdk/blob/7ba4fb881d85406f44a5af8169fb7200fa7c8e49/src/mcp/cli/cli.py#L451-L453.

It has no relationship to the MCP protocol or the low-level Server class — it's purely a Python/uv packaging convenience that originated in jlowin's original FastMCP.

Why we can't just remove it

Real-world usage is significant (~772 files on GitHub, ~95+ repos):

• awslabs/mcp (8.5k★) — 47 server files use it as their standard template
• mindsdb/mindsdb (38.8k★) — uses it
• redis/mcp-redis (461★), volcengine/mcp-server, camel-ai/camel, plus ~15–20 community servers

When jlowin's fastmcp package removed the same parameter, it caused 8+ breakage issues across awslabs/mcp, zotero-mcp, panther-labs, ClickHouse — all TypeError: unexpected keyword argument 'dependencies'.

The replacement gap

The v2 examples were migrated to PEP 723 inline script metadata:

# /// script
# dependencies = ["pyautogui", "Pillow"]
# ///

But this does not currently work with mcp install / mcp dev. Those commands generate uv run --with mcp[cli] mcp run server.py — uv only parses PEP 723 when the script is the direct target, not when it's an argument to another command. So the feature was removed without a working replacement.

Options (Claude's ideas)

A. Keep dependencies, do nothing

Simplest. Works. Mixes packaging metadata into server code, which is architecturally questionable.

B. Deprecate → PEP 723, teach the CLI to parse it

Add a DeprecationWarning to the parameter. Update mcp dev/mcp install to parse # /// script blocks from the target file and convert dependencies = [...] to --with flags. PEP 723 has a ~15-line reference parser in the spec. Remove the parameter in a later release.

C. Follow FastMCP 2.0's lead: config file

jlowin's FastMCP 2.0 replaced dependencies= with a fastmcp.json config file (source/environment/deployment sections), deprecated for ~3.5 months, then removed. They also expanded install to 7 targets (claude-desktop, claude-code, cursor, gemini-cli, goose, mcp-json, stdio). This is the richest solution but the most work, and overlaps with what FastMCP 2.0 already provides.

D. Deprecate → point users at FastMCP 2.0

If the official SDK's CLI is meant to stay minimal, deprecate dependencies and mcp install/mcp dev together, pointing users to fastmcp for deployment tooling.

_{AI Disclaimer}

Commencez par la gestion des dépendances dans src/mcp/cli/cli.py aux emplacements référencés de mcp dev et mcp install, puis suivez la manière dont MCPServer expose les dépendances. Comparez ces chemins avec les exemples de PEP 723 et les alternatives de configuration répertoriées. Le travail est terminé lorsqu’une décision à long terme documentée spécifie clairement le comportement concerné de CLI et de MCPServer.