Design: future of `dependencies` parameter on MCPServer

[maxisbey]

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

python-sdk/src/mcp/cli/cli.py

Lines 261 to 262 in 7ba4fb8

	if hasattr(server, "dependencies"):
	with_packages = list(set(with_packages + server.dependencies))

and

python-sdk/src/mcp/cli/cli.py

Lines 451 to 453 in 7ba4fb8

	server_dependencies = getattr(server, "dependencies", []) if server else []
	if server_dependencies:
	with_packages = list(set(with_packages + server_dependencies))

.

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}

[Kludex]

What high profile users?

[Kludex]

As I mentioned in person, I believe reintegrating the previous removed dependencies parameter was a mistake.

I don't think it's a reliable way to have dependencies. It also opens space for an uncontrolled package versioning setup i.e. you can't pin the transitive dependencies (which may contain vulnerabilities, and there is not way to reliably scan those).

---

The biggest problem here is not having a clear documentation about how to distribute the MCP servers built with the SDK.