Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

docs: badge 4.2.0 features and add the 4.1 to 4.2 upgrade guide (#6436)

nate nowackef43d5deb824
diff --git a/docs/apps/development.mdx b/docs/apps/development.mdx
index df7744032..6238a69c8 100644
--- a/docs/apps/development.mdx
+++ b/docs/apps/development.mdx
@@ -61,6 +61,8 @@ With `--host 0.0.0.0`, open the dev UI through `localhost` or an IP address. To
### npm registry
+<VersionBadge version="4.2.0" />
+
On first run, the dev server downloads the `@modelcontextprotocol/ext-apps` package from the public npm registry and caches it. If your network only allows an internal npm mirror, set `npm_config_registry` (or `NPM_CONFIG_REGISTRY`) to the mirror's URL, the same variable npm reads. When neither is set, or the value is empty, the dev server uses `https://registry.npmjs.org`. The mirror must serve the standard npm tarball layout.
```bash
diff --git a/docs/cli/client.mdx b/docs/cli/client.mdx
index ccceb21ee..3c234dd12 100644
--- a/docs/cli/client.mdx
+++ b/docs/cli/client.mdx
@@ -35,6 +35,8 @@ By default, only tools are shown. Add `--resources` or `--prompts` to include th
fastmcp list server.py --resources --prompts
```
+<VersionBadge version="4.2.0" />
+
`--skills` lists the server's [Skills extension](/servers/skills) entries with each skill's files. A server that doesn't advertise the extension shows no skills and says why.
```bash
diff --git a/docs/clients/client-groups.mdx b/docs/clients/client-groups.mdx
index e3738091b..ded27a580 100644
--- a/docs/clients/client-groups.mdx
+++ b/docs/clients/client-groups.mdx
@@ -75,6 +75,8 @@ Discovered routes outlive the group's context. After the last exit, `resolve_too
## List skills across servers
+<VersionBadge version="4.2.0" />
+
`list_skills()` collects [Skills extension](/servers/skills) entries from every client that opted into it, keyed by server name, since two servers can publish the same skill URI. Clients created without `SkillsClientExtension()`, including those from `from_config`, and servers that don't advertise the extension are left out.
```python
diff --git a/docs/docs.json b/docs/docs.json
index 250f70525..c3d6d9256 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -369,6 +369,7 @@
"group": "Upgrading",
"icon": "up",
"pages": [
+ "getting-started/upgrading/from-fastmcp-4-1",
"getting-started/upgrading/from-fastmcp-3",
"getting-started/upgrading/from-fastmcp-2",
"getting-started/upgrading/from-mcp-sdk-v1",
diff --git a/docs/getting-started/upgrading/from-fastmcp-4-1.mdx b/docs/getting-started/upgrading/from-fastmcp-4-1.mdx
new file mode 100644
index 000000000..f0ed9c5e4
--- /dev/null
+++ b/docs/getting-started/upgrading/from-fastmcp-4-1.mdx
@@ -0,0 +1,76 @@
+---
+title: Upgrading from FastMCP 4.1
+sidebarTitle: "From FastMCP 4.1"
+description: What changes when you upgrade from FastMCP 4.1 to 4.2
+icon: up
+---
+
+FastMCP 4.2 raises the Python floor and deprecates the 4.1 skills API. Everything else in 4.1 keeps working. This page covers what to check before upgrading and what to move before 4.3.
+
+```bash
+pip install "fastmcp>=4.2"
+```
+
+## Python 3.11 or newer
+
+FastMCP 4.2 requires Python 3.11. On Python 3.10, your installer keeps resolving to 4.1.x, so a project that must stay on 3.10 should pin `fastmcp<4.2`. To take 4.2, move the project to Python 3.11 and raise `requires-python` to match:
+
+```toml
+[project]
+requires-python = ">=3.11"
+dependencies = ["fastmcp>=4.2"]
+```
+
+## The 4.1 skills API
+
+The providers in `fastmcp.server.providers.skills` and the helpers in `fastmcp.utilities.skills` still work in 4.2 and are removed in 4.3. Each emits a deprecation warning that names its replacement. The new API lives in `fastmcp.skills`: author skills with `Skill`, serve a folder with `SkillsDirectoryProvider` from `fastmcp.skills.provider`, and read them from a client with `client.read_skill()`.
+
+| 4.1 | 4.2 |
+| --- | --- |
+| `SkillsDirectoryProvider(root)` from `fastmcp.server.providers.skills` | `SkillsDirectoryProvider(root)` from `fastmcp.skills.provider` |
+| `ClaudeSkillsProvider()` and the other vendor presets | `SkillsDirectoryProvider(Path.home() / ".claude" / "skills")` with the preset's folder |
+| `SkillProvider(path)` | `SkillCatalogProvider([Skill.from_directory(path)])` |
+| `list_skills(client)` | `client.list_skill_resources()` |
+| `download_skill()` / `sync_skills()` | `client.read_skill(uri)` then `skill.to_directory(path)` |
+| `Skill` as a wire model | `MCPSkill`; `Skill` is now the authoring class |
+
+The usual change is one import:
+
+```python
+from pathlib import Path
+
+from fastmcp import FastMCP
+from fastmcp.skills.provider import SkillsDirectoryProvider
+
+root = Path("skills")
+mcp = FastMCP("Skills", providers=[SkillsDirectoryProvider(root)])
+```
+
+The new provider refuses folders the old one accepted, such as a `SKILL.md` whose frontmatter name doesn't match its folder. The 4.1 provider's warning lists each folder it would refuse and the fix, so start the server once on 4.2, fix what it reports, then switch. The [Skills](/servers/skills) page has the full migration table and the client-side details.
+
+## Annotated dependencies
+
+4.2 also accepts dependencies as `Annotated` metadata. This is optional; `Depends()` defaults keep working. An alias declares a dependency once and gives the parameter its real type for type checkers:
+
+```python
+from typing import Annotated
+
+from fastmcp import FastMCP
+from fastmcp.dependencies import Depends
+
+mcp = FastMCP("Demo")
+
+
+def get_config() -> dict:
+ return {"api_url": "https://api.example.com"}
+
+
+Config = Annotated[dict, Depends(get_config)]
+
+
+async def fetch(query: str, config: Config) -> str:
+ return f"Fetching '{query}' from {config['api_url']}"
+```
+
+A parameter takes one form or the other: an `Annotated` dependency combined with a `Depends()` default raises `TypeError`. See [Annotated Dependencies](/servers/dependency-injection#annotated-dependencies).
diff --git a/docs/servers/dependency-injection.mdx b/docs/servers/dependency-injection.mdx
index 3aee4c812..e6cde446b 100644
--- a/docs/servers/dependency-injection.mdx
+++ b/docs/servers/dependency-injection.mdx
@@ -359,6 +359,8 @@ async def fetch_data(
### Annotated Dependencies
+<VersionBadge version="4.2.0" />
+
A dependency can also go in the parameter's annotation instead of its default. The parameter keeps its declared type, so a type checker sees `config` as a `dict` rather than a `Depends` object, and a direct call that forgets it fails with a `TypeError` instead of running with the marker. An alias carries the type and the dependency together, so every tool that needs the config reads the same declaration.
```python
diff --git a/docs/servers/prompts.mdx b/docs/servers/prompts.mdx
index 1cbd2ca41..29f89e641 100644
--- a/docs/servers/prompts.mdx
+++ b/docs/servers/prompts.mdx
@@ -228,6 +228,8 @@ If an argument already has an explicit description β€” via `Annotated[x, "..."]`
### Argument Titles
+<VersionBadge version="4.2.0" />
+
An argument's name is what clients send, so it is usually short. To show clients a human-readable label instead, give the parameter a title with `Field(title=...)`:
```python