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}

Comece pelo tratamento de dependências em src/mcp/cli/cli.py nos locais referenciados de mcp dev e mcp install e, em seguida, rastreie como MCPServer expõe as dependências. Compare esses caminhos com os exemplos de PEP 723 e com as alternativas de configuração listadas. Considera-se concluído quando houver uma decisão de longo prazo documentada, com o comportamento afetado de CLI e MCPServer claramente especificado.